Skip to content

Native browser command reference ​

Flowstride and Flowstride Pro share the commands below. Put them inside a complete Feature/Scenario, using flow.<area>.<action> followed by a JSON object and an optional semicolon. Empty arguments are written {}. Unknown actions and fields fail explicitly.

The structured command index includes every object command and links to its examples. This page covers profiles, time control, downloads, accessibility, components and browser evidence. For setup and ordering, see native browser workflows.

Names, paths and values ​

Names are 1–80 characters, start with a letter or number, and use only letters, numbers, _, . and -. Use distinct names within their scope. Fixture, baseline, certificate, storage-state and download paths must resolve inside the project, including symlink targets. A command's returned value is not automatically assigned to a DSL variable.

Timeouts are positive integer milliseconds. JSON booleans and numbers retain their types: use true for a boolean property check and "true" for an attribute that literally contains that string.

Profiles and runtime settings ​

A browser profile lets you keep a separate browser session for each test user. For example, stay signed in as a customer in one profile and as an administrator in another. Switching profiles takes you back to that user’s page and keeps their cookies and storage separate.

CommandRequired fieldsOptional fields / behavior
flow.browser.createnameoptions; creates and selects an isolated profile
flow.browser.usenameSelect an existing profile and its remembered page
flow.browser.closenameClose a named profile; default cannot be closed this way
flow.browser.listNone: {}Return available profile names; no automatic DSL assignment
flow.browser.offlinevalue: booleanApplies to the current profile
flow.browser.permissionspermissions: string arrayOptional origin
flow.browser.clearPermissionsNone: {}Remove granted permissions from the current profile
flow.browser.geolocationlatitude, longitudeNonnegative accuracy; grant the application's geolocation permission separately

Profiles reset between files. flow.switchTo selects tabs within the selected profile; saved sessions are snapshots applied to that profile.

For a location test, create a separate profile and grant permission for the app’s origin. This example uses the configured base URL and a page that asks for location.

flow
flow.browser.create {
  "name": "lagos-customer",
  "options": {
    "locale": "en-NG"
  }
};
flow.browser.permissions {
  "permissions": ["geolocation"],
  "origin": "{{env.BASE_URL}}"
};
flow.browser.geolocation {
  "latitude": 6.5244,
  "longitude": 3.3792
};
flow.open "/delivery";
flow.browser.clearPermissions {};
flow.browser.list {};
flow.browser.use { "name": "default" };
flow.browser.close { "name": "lagos-customer" };

To test offline behavior, open a page with an offline UI, toggle the current profile’s network and exercise a control that checks connectivity.

flow
flow.browser.offline { "value": true };
flow.click button "Check connection";
flow.expect visible "You are offline";
flow.browser.offline { "value": false };

Browser settings ​

Use these keys in configuration browserOptions or a new profile's options. New profiles inherit context settings, but do not automatically inherit the default profile's configured authentication storage.

SettingsAccepted values
viewportPositive integer width/height, or null
screenPositive integer width/height
deviceScaleFactorPositive number
hasTouch, isMobileBoolean; Firefox rejects explicit isMobile: true
locale, timezoneId, userAgentStrings; see compatibility limits
colorSchemelight, dark, no-preference, or null
contrastno-preference, more, or null
forcedColorsactive, none, or null
reducedMotionreduce, no-preference, or null
javaScriptEnabled, bypassCSP, ignoreHTTPSErrors, offlineBoolean
acceptDownloads, strictSelectorsBoolean
serviceWorkersallow or block
permissionsArray of permission names; engine support varies
geolocationlatitude from −90 to 90; longitude from −180 to 180; optional nonnegative accuracy
extraHTTPHeadersObject of string header names and string values
httpCredentialsusername, password; optional origin and send (always or unauthorized)
proxyserver; optional bypass, username, password
storageStateProject-local file or a storage-state object containing cookies and origins; this differs from a named saved session
clientCertificatesArray of origin plus project-local certPath/keyPath or pfxPath; optional passphrase
baseURLContext URL setting; Flowstride browser/API relative commands use the run's BASE_URL / baseUrl

Recording paths use Flowstride's evidence configuration. Callbacks, arbitrary browser launch arguments and other unlisted context keys are not supported JSON settings. Engine/platform-specific options still require qualification.

Retrying assertions ​

flow.assert.that retries a browser condition using readable text or label, a scoped readable target, a role and name, or a selector. See every condition and example. To check already-extracted data, use flow.assert.value.

Network routes and events ​

CommandRequired fieldsOptional fields / behavior
flow.network.routename, urlmode, method, times, delay, requestBody and the response or request options below
flow.network.unroutenameRemove a registered route, including one that exhausted its match count
flow.network.armname, urlkind: response (default) or request; optional method, timeout, response status filter
flow.network.waitnameConsume the armed event and retain its captured data
flow.network.expectname plus an expectationstatus, method, header, dotted body path, exact JSON equals, string contains

Arm before the triggering action; wait before asserting the captured result. The timeout starts at arming. A request event has no response status. Rules, waiters and captured data belong to the current profile. Native waits capture one matching event, not a permanent request history.

Route modes:

  • fulfill (default): optional status, headers, contentType, and one of json, text body, or project-local fixture.
  • patch: fetch the real response, then shallow-merge a JSON object or replace the body; optional response status/headers. Nested objects are not deep-merged.
  • continue: forward the request; optional request object can change url, method, string headers or text body.
  • abort: block the request; response and request-rewrite fields are invalid.

times is a positive maximum match count. After it is reached, subsequent requests fall through. delay adds latency and requestBody matches a typed JSON field before applying the route. See body-aware route and capture examples.

Downloads ​

CommandRequired fieldsOptional fields / behavior
flow.download.armnametimeout; observe the current page's next download
flow.download.savename, fileWait for the armed event and save to a new project-local destination
flow.download.expectname plus an expectationSuggested filename, exact byte size, minSize, text contains, complete json, lowercase 64-character sha256

Arm before the click. A saved destination must not already exist; use a fresh name such as downloads/report-$uuid.json for repeatable runs. filename checks the browser's suggested filename, not your chosen destination name. Text/JSON checks have a 20 MiB limit; hash checks stream the file. Downloads are scoped to the profile; switch back before saving/asserting its event.

See the export, save and verify example.

Browser clock ​

If your app enables Resend code after a 60-second countdown, you can advance the browser clock and check that the button becomes available. This lets you exercise the countdown in seconds of real time.

CommandFieldsBehavior
flow.clock.installOptional timeInstall page clock control; optional date string or numeric time
flow.clock.pauseAttimeAdvance/pause at the specified date/time
flow.clock.resume{}Resume time
flow.clock.runFormillisecondsAdvance time while running scheduled timers
flow.clock.fastForwardmillisecondsJump time; repeating timers behave differently from runFor
flow.clock.setFixedTimetimeFix the reported current time without the same timer behavior as pausing
flow.clock.setSystemTimetimeChange the clock's system time

Advances are integer milliseconds from 0 through 86,400,000. Install before the application creates timers; pause explicitly when an exact tick count matters. These commands do not control backend or operating-system time.

For a page with a countdown, install the clock, pause it at a known time and advance the page through five seconds of scheduled ticks. Resume when the page can proceed in real time.

flow
flow.clock.install { "time": "2026-03-01T10:00:00Z" };
flow.clock.pauseAt { "time": "2026-03-01T10:01:00Z" };
flow.open "/countdown";
flow.clock.runFor { "milliseconds": 5000 };
flow.clock.resume {};

Use fastForward to model a jump such as the browser returning from sleep. A timer fires at most once during that jump. setSystemTime moves the system-time value without firing timers. For a fixed date label while timers continue, use setFixedTime.

flow
flow.clock.fastForward { "milliseconds": 60000 };
flow.clock.setSystemTime { "time": "2026-03-01T10:10:00Z" };
flow.clock.setFixedTime { "time": "2026-03-01T10:30:00Z" };

Function spies and stubs ​

If clicking Place order should send one analytics event, a spy can count the call while the original function runs. A stub controls what the function returns or what error it throws. For example, make the quote function throw so you can check that the page shows Try again later.

CommandRequired fieldsOptional fields / behavior
flow.stub.installname, dotted targetmode: spy (default), return, throw; optional value, error, async, beforeLoad
flow.stub.expectname plus an expectationExact count, minCount, one matching argument array args, timeout
flow.stub.restorenameRestore the original function on the current page

The target must be a replaceable function reachable from window. Use async: true for a promise result or rejection. Use beforeLoad to install an initializer for functions available at that point in the page’s lifecycle. For module-private functions, expose a replaceable entry point in the test build.

Doubles belong to the page; a same-name double on another profile/page is separate. Call arguments are compared with JSON-compatible captured values. Restore before replacing an existing name.

The spy, call assertion and restore example observes a real function. The example below installs the quote stub and restores the original function after checking the fallback.

flow
flow.stub.install {
  "name": "quote-outage",
  "target": "shopQuotes.calculate",
  "mode": "throw",
  "error": "Quote service unavailable"
};
flow.click button "Get quote";
flow.expect visible "Try again later";
flow.stub.restore { "name": "quote-outage" };

Traces and HAR ​

A trace helps you retrace what happened during a test. If checkout fails after Review order, you can inspect the click and what the page looked like at that point.

A HAR (HTTP Archive) records the requests the browser made and the responses it got. For example, record the order list while the service is available, then replay that response in a later test of the order page.

CommandFieldsBehavior
flow.trace.startOptional nameStart tracing the current profile; rejects an already-active trace
flow.trace.stop{}Finalize the current profile's trace ZIP
flow.har.replayfile; optional url, notFoundRead an existing local HAR; unmatched requests abort by default, or explicitly fallback

Set configuration trace: true for automatic tracing or use explicit start/stop for a bounded trace. HAR recording is configured with har: true before context creation; there is no flow.har.record action. Replay reads a project-local HAR within 100 MiB and does not update it. See evidence workflows and browser limits.

flow
flow.trace.start { "name": "checkout" };
flow.open "/checkout";
flow.click button "Review order";
flow.trace.stop {};

In a separate run, use a HAR recorded for the same app origin to replay a specific GET endpoint before opening the page.

flow
flow.har.replay {
  "file": "fixtures/orders.har",
  "url": "**/api/orders",
  "notFound": "abort"
};
flow.open "/orders";

Accessibility and ARIA ​

CommandRequired fieldsOptional fields / behavior
flow.a11y.scanNone: {}name (default accessibility), selector arrays include/exclude, tags, rules, disableRules, impacts, maxViolations (default 0)
flow.a11y.snapshotnameselector (default body), baseline, timeout, update
flow.a11y.matchNonempty yamlselector (default body), timeout; retries a complete-tree comparison

Impacts are minor, moderate, serious, critical. The scan threshold counts violation entries after selected impact filtering, not the number of affected DOM nodes. A structured axe report is retained even when the scan fails.

A snapshot without baseline captures evidence. With baseline, it compares a complete YAML tree. Deliberate writes require local --update-baselines; update: true does not bypass that CLI requirement. CI refuses baseline writes. snapshot compares its capture once; use match for a retrying inline tree comparison. These are exact comparisons, not a partial snapshot matcher or visual screenshot baseline.

See scan, inline YAML and file-baseline examples.

Components ​

A component test loads one piece of the interface on its own. For example, you can give an order badge the status Pending, change it to Approved, and check that the displayed label updates.

CommandRequired fieldsOptional fields / behavior
flow.component.mountframework: vanilla, react, or vue; project-local moduleexport (default default), JSON props, project-local css array
flow.component.updateprops objectApply the next props; framework behavior applies
flow.component.unmount{}Unmount the current page's mounted component

Install the project's React/React DOM or Vue packages as appropriate. Flowstride manages a local Vite harness; it does not automatically load your app's Vite configuration, providers, router or backend. React updates follow React rendering; Vue replaces supplied prop keys; vanilla update remounts the factory. Mounting another component disposes the previous harness.

This example uses a React component at components/OrderBadge.tsx that displays its status prop. See component setup and complete examples.

flow
flow.component.mount {
  "framework": "react",
  "module": "components/OrderBadge.tsx",
  "props": {
    "status": "Pending"
  }
};
flow.expect visible "Pending";
flow.component.update {
  "props": {
    "status": "Approved"
  }
};
flow.expect visible "Approved";
flow.component.unmount {};

Interpret a failed command ​

Native assertions preserve successful lookup checks and failed conditions separately. The terminal, interactive views and CI JSON/JUnit retain the target, expected/actual condition, timeout and source location. Dependent checks remain not evaluated when a prerequisite is missing. See assertions and diagnostics.

For complete workflows beyond individual command arguments, use browser environments, component testing, tabs and iframes, and the feature map.

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