Skip to content

Core concepts ​

A flow file describes behavior ​

Flowstride (FS) uses the .flow extension. A .flow file has exactly one Feature declaration at the top, followed by one or more Scenario blocks. Each scenario groups commands under Given, When, optional intermediate And blocks, and a final Then.

flow
Feature: Account access

Scenario: A member signs in

Given "The login page is open"
  flow.open "/login";

When "The member enters valid credentials"
  flow.type "Email" "{{env.TEST_EMAIL}}";
  flow.type "Password" "{{env.TEST_PASSWORD}}";
  flow.click button "Login";

Then "The account is available"
  flow.expect visible "Logout";

Given establishes context. When performs the journey. Then contains the scenario's final commands and checks. All three are required, and Given comes first.

Then is terminal. After its commands, the only new declaration allowed is another Scenario. An And, another Then, an action block, an alias declaration, or another Feature cannot follow it. Put multiple final assertions or a final action such as logout inside the same Then block.

And is an intermediate assertion block before Then. It accepts flow.expect, supported native assertions such as flow.assert.that, and custom assertion plugins. Use another When for further actions before the final block. Multiple commands can share one description. See assertions and diagnostics.

RuleHow to apply it
One Feature per fileDeclare it before aliases or scenarios; comments and blank lines may come first
Required scenario structureUse one initial Given, at least one When, and one final Then
Additional actionsAdd When blocks before Then
Intermediate checksAdd assertion-only And blocks before Then
Several final checksPut their commands together inside the single Then
Another journeyBegin a new Scenario after the final block

Where JavaScript and TypeScript fit ​

Import named functions under Feature and call them inside a step. A helper can apply a business rule to an array, throw an error that identifies a bad record, or receive the active Playwright page. The .flow file owns the sequence and its expected outcome. Use a fixture when FS should release a resource on retry or failure. Use the SDK when an extension needs runner services such as attaching a file. Work through a real catalog test

The project is the execution boundary ​

Run commands from your project folder. Configuration, helpers, fixtures, plugins, flow targets, and output paths must stay inside it, including symlink targets. Keep reusable assets in fixtures/ rather than reaching outside the project.

Variables have different jobs ​

FormPurpose
{{env.BASE_URL}}Read an environment value
$randomEmailGenerate a value and remember it
@randomEmailReuse the generated value
@userIdReuse an extracted value in the same flow file
@global[userId]Reuse an explicitly global extracted value in the same process
let game = "flowstride:game"Register a command alias, not a general variable assignment

See variables and sessions. Process memory is not a shared store between parallel Flowstride Pro workers.

API and UI share the journey ​

API setup, extraction, browser actions and assertions can live in one scenario. Share generated credentials explicitly and assert each API result before continuing. API and UI in one flow shows signup, administrator approval, browser login and Cloud OTP verification.

A manual design and a manual run are different records ​

A design records what should be tested. A run records what a tester actually did and the outcome. Saving a design does not establish a passing result. Manual testing explains this lifecycle in detail.

Objects, punctuation and debug controls ​

Native object commands use JSON: quote keys and strings, use lowercase booleans and omit trailing commas. The semicolon terminates the completed command, after }; do not insert one after the opening brace. A JSON property is an option or input to that command, not an independent executable step.

only.Scenario: focuses one scenario in its file. A stop. block halts after its first successful command. Both are debugging controls; remove them before a complete acceptance run. Execution and failures explains discovery, setup files and incomplete results.

Flowstride is MIT licensed. Flowstride Cloud offers free and paid workspace plans.