Your first automated flow
Install Flowstride (FS) with npm, initialize a project, and write a test for your application. This guide uses a login page to show browser actions and assertions. Use a test account and adapt the URL, labels, button text, and expected result to your application.
1. Install and initialize
In a new project folder, run:
npm init -y
npm install --save-dev flowstride
npx flowstride init
npx flowstride runIn an existing npm project, skip npm init -y.
On a fresh install, init copies the starter and advanced .flow files and checks for Chromium. The first run opens the live dashboard and runs browse-catalog.flow followed by login.flow against the bundled local app. Once these pass, continue below to write a test for your own app. Practice examples
If browser setup did not complete, run:
npx flowstride install2. Configure your application
Create a .env file in the project root. Set BASE_URL to your application's test URL and add your test account credentials:
BASE_URL=http://127.0.0.1:3000
TEST_EMAIL=tester@example.test
TEST_PASSWORD=replace-with-your-test-account-passwordFlowstride loads .env automatically when you run a flow. With this BASE_URL, flow.open "/login"; opens http://127.0.0.1:3000/login. The starter configuration defaults to flows/examples/starter. Pass the path of your new test when you run it.
For a local application, start it in a separate terminal using its normal startup command and leave it running. For a hosted application, set BASE_URL to its test environment URL.
Use credentials for an account that already exists in your test environment. Keep .env out of Git and share placeholder values in .env.example instead. Configuration and environments explains profile files and CI secrets.
Alternative: use a configuration file
You can set the same base URL in flowstride.config.json instead:
{
"testDir": "flows/application",
"baseUrl": "http://127.0.0.1:3000"
}Choose either place for the base URL. If both are set, BASE_URL takes precedence over baseUrl. A configuration file is also useful when you want to customize timeouts, media, or other execution settings.
3. Write the flow
Create flows/application/account-login.flow for this test.
Feature: Account access
Scenario: A customer can sign in
Given "The login page is open"
flow.open "/login";
When "The customer enters valid credentials"
flow.type input "Email" "{{env.TEST_EMAIL}}";
flow.passcode input "Password" "{{env.TEST_PASSWORD}}";
flow.click button "Sign in";
Then "The customer is signed in"
flow.expect visible "Logout";This example assumes a /login page with inputs labeled Email and Password, a Sign in button, and visible Logout text after successful login. Change those values to match your application.
Given establishes the starting state. When performs the customer action. Then checks the visible result. Keep the assertion specific enough to distinguish a successful login from the page merely loading.
To test the password eye control before submitting, follow the password visibility walkthrough. It uses the bundled practice account.
4. Run and inspect
npx flowstride run flows/application/account-login.flowThe live dashboard opens in your browser. The terminal prints its local URL. Select a step to inspect its screen and network records. Close the dashboard or press Ctrl+C when you finish.
5. Run the same flow in CI mode
With your application still available, run:
npx flowstride run flows/application/account-login.flow --ciA successful run exits with code 0 and writes reports under flowstride-artifacts. Change the expected Logout text to something that is absent, run again, and confirm that the assertion fails with a nonzero exit code. Restore the expected text afterward.
Commit package.json, package-lock.json, the flow, and any configuration file you added. Supply test credentials through CI secrets. For a local application that Flowstride should start automatically during CI, configure a managed local server. See native CI to generate a GitHub Actions workflow.
Optional: prepare data with an API
Browser and API commands can share a scenario. If your application provides a test-data endpoint, a setup call could look like this:
flow.post "/api/test/customers" with reqBody
"""
{
"email": "reader@example.test",
"name": "Documentation Reader"
}
"""
flow.expect status "201";The endpoint, request fields, response status, authentication, and account preparation must match your application. Flowstride does not create that endpoint. Put setup commands under Given in a complete scenario, assert the response, and use the same prepared customer in the browser. See the API command reference.
For the complete signup → API approval → browser login → OTP pattern, see API and UI in one flow. Shared test data does not require a separate runner or browser plugin.
Optional: use VS Code
Open the project folder in VS Code and install Flowstride Automation from publisher flowstride for highlighting, completions, diagnostics, Go to Definition for imported helpers, and Run Test. The extension uses the CLI installed in your project.
The current extension requires a trusted workspace to run project code. If VS Code cannot find the intended Node executable, configure flowstride.nodePath to a Node.js 22.12+ executable. New runtime commands can arrive before editor completions, so the engine's parser and this command reference remain authoritative. You can also use any editor and the terminal commands above.
