flowstride 1.0.20 → 1.0.22

package/examples/native-workflows/tables-and-cells/README.md

@@ -0,0 +1,118 @@
+# Search tables, target cells and reuse their values
+
+Flowstride can interact with a table through readable controls, exact selectors or indexed coordinates. It can extract a cell's text and use it in another page in the same test.
+
+| Requirement | Value |
+| --- | --- |
+| Engine | OS or Cloud |
+| Browser | Chromium, Firefox or WebKit |
+| Application | Shared local demo |
+| Cloud account | Optional |
+
+Complete the [shared setup](../README.md) and leave the demo application running.
+
+## Search, choose an action and reuse a cell
+
+The demo has two orders: FS-101 is Pending and FS-102 is Approved. Its search control hides unmatched rows; selecting a row or its View button opens that order's details.
+
+[search-extract-reuse.flow](flows/search-extract-reuse.flow):
+
+```flow
+Feature: Table and cell reuse
+Scenario: Search, extract and reuse a table value
+Given "The orders table is open"
+  flow.open "/orders";
+When "Find the approved order"
+  flow.type input "Search orders" "FS-102";
+  flow.assert.that {
+    "selector": "#orders tbody tr:not([hidden])",
+    "condition": "count",
+    "value": 1
+  };
+  flow.assert.that {
+    "selector": "#orders tbody tr:has(td:text-is('FS-102')) td:nth-child(3)",
+    "condition": "text",
+    "value": "Approved"
+  };
+When "Extract the order and open its row action"
+  flow.extract text "table[0] tr[2] td[0]" as "selectedOrder";
+  flow.click button "View" inside "table[0] tr[2] td[3]";
+And "The selected order is shown"
+  flow.expect text "Order @selectedOrder";
+When "Reuse the cell on another page"
+  flow.open "/reuse";
+  flow.type input "Selected value" "@selectedOrder";
+  flow.click button "Apply value";
+Then "The reused value remains correct"
+  flow.expect text "Selected FS-102";
+```
+
+```sh
+npx flowstride run workflow-examples/tables-and-cells/flows/search-extract-reuse.flow --ci
+```
+
+Expected: one visible matching row, Approved in the selected status cell, `Order FS-102` after the exact row action, and `Selected FS-102` after navigation and reuse. The run exits `0`.
+
+`flow.type` uses the application's search input. The application implements filtering. The assertion excludes rows hidden by this fixture's `hidden` attribute; adapt it if your app removes rows or uses another hiding mechanism.
+
+The extraction stores the text as `@selectedOrder`. Extraction itself does not assert that the value is correct; the following outcome checks do.
+
+## Indexed table/cell targets
+
+[coordinates.flow](flows/coordinates.flow) demonstrates direct cell selection and a repeated button inside an exact cell:
+
+```flow
+Feature: Table coordinates and exact cell actions
+
+  Scenario: Select a cell and a repeated row action
+    Given "The unfiltered orders table is open"
+      flow.open "/orders";
+
+    When "Select the first cell of the second data row"
+      flow.click "table[0] tr[2] td[0]";
+
+    And "The second order is selected"
+      flow.expect text "Order FS-102";
+
+    When "Click the button in the first data row's action cell"
+      flow.click button "View" inside "table[0] tr[1] td[3]";
+
+    Then "The first order is selected"
+      flow.expect text "Order FS-101";
+```
+
+```sh
+npx flowstride run workflow-examples/tables-and-cells/flows/coordinates.flow --ci
+```
+
+Expected: clicking `table[0] tr[2] td[0]` selects FS-102, then clicking View in the first data row's action cell selects FS-101.
+
+| Target | Meaning in this fixture |
+| --- | --- |
+| `table[0]` | First table |
+| `table[0] tr[0]` | Header row |
+| `table[0] tr[1]` | First data row |
+| `table[0] tr[2] td[0]` | First data cell of the second data row |
+| `table[0] tr[1] td[3]` | Action cell of the first data row |
+
+Indexes are zero-based. Header rows count as rows, and hidden matching DOM rows can still affect indexes. CSS `nth-child` positions, used in the status assertion, are one-based.
+
+## Deliberate failure
+
+```sh
+npx flowstride run workflow-examples/tables-and-cells/negative/wrong-cell-value.flow --ci
+```
+
+That file expects Rejected where the fixture contains Approved. It must fail, retain evidence and exit nonzero.
+
+## Adapting to changing tables
+
+For sorted, filtered or paginated tables, prefer a stable record identifier when position is not what you are testing. For example:
+
+```flow
+flow.click "#orders tbody tr:has(td:text-is('FS-102')) button";
+```
+
+The match must identify the intended record uniquely. Pagination, virtual scrolling and data loading remain application behavior: navigate or load the row before targeting it. An indexed HTML-table helper is not a universal query language for every virtual grid or ARIA treegrid.
+
+See the [table reference](https://docs.flowstride.io/flow-language/flow-elements/table) and [variable reuse](../variables-and-reuse/README.md).

package/examples/native-workflows/tables-and-cells/flows/coordinates.flow

@@ -0,0 +1,17 @@
+Feature: Table coordinates and exact cell actions
+
+  Scenario: Select a cell and a repeated row action
+    Given "The unfiltered orders table is open"
+      flow.open "/orders";
+
+    When "Select the first cell of the second data row"
+      flow.click "table[0] tr[2] td[0]";
+
+    And "The second order is selected"
+      flow.expect text "Order FS-102";
+
+    When "Click the button in the first data row's action cell"
+      flow.click button "View" inside "table[0] tr[1] td[3]";
+
+    Then "The first order is selected"
+      flow.expect text "Order FS-101";

package/examples/native-workflows/tables-and-cells/flows/search-extract-reuse.flow

@@ -0,0 +1,27 @@
+Feature: Table and cell reuse
+Scenario: Search, extract and reuse a table value
+Given "The orders table is open"
+  flow.open "/orders";
+When "Find the approved order"
+  flow.type input "Search orders" "FS-102";
+  flow.assert.that {
+    "selector": "#orders tbody tr:not([hidden])",
+    "condition": "count",
+    "value": 1
+  };
+  flow.assert.that {
+    "selector": "#orders tbody tr:has(td:text-is('FS-102')) td:nth-child(3)",
+    "condition": "text",
+    "value": "Approved"
+  };
+When "Extract the order and open its row action"
+  flow.extract text "table[0] tr[2] td[0]" as "selectedOrder";
+  flow.click button "View" inside "table[0] tr[2] td[3]";
+And "The selected order is shown"
+  flow.expect text "Order @selectedOrder";
+When "Reuse the cell on another page"
+  flow.open "/reuse";
+  flow.type input "Selected value" "@selectedOrder";
+  flow.click button "Apply value";
+Then "The reused value remains correct"
+  flow.expect text "Selected FS-102";

package/examples/native-workflows/tables-and-cells/negative/wrong-cell-value.flow

@@ -0,0 +1,27 @@
+Feature: Table and cell reuse
+Scenario: Search, extract and reuse a table value
+Given "The orders table is open"
+  flow.open "/orders";
+When "Find the approved order"
+  flow.type input "Search orders" "FS-102";
+  flow.assert.that {
+    "selector": "#orders tbody tr:not([hidden])",
+    "condition": "count",
+    "value": 1
+  };
+  flow.assert.that {
+    "selector": "#orders tbody tr:has(td:text-is('FS-102')) td:nth-child(3)",
+    "condition": "text",
+    "value": "Rejected"
+  };
+When "Extract the order and open its row action"
+  flow.extract text "table[0] tr[2] td[0]" as "selectedOrder";
+  flow.click button "View" inside "table[0] tr[2] td[3]";
+And "The selected order is shown"
+  flow.expect text "Order @selectedOrder";
+When "Reuse the cell on another page"
+  flow.open "/reuse";
+  flow.type input "Selected value" "@selectedOrder";
+  flow.click button "Apply value";
+Then "The reused value remains correct"
+  flow.expect text "Selected FS-102";

package/examples/native-workflows/variables-and-reuse/README.md

@@ -0,0 +1,140 @@
+# Variables, reuse and saved browser sessions
+
+Flowstride can generate test data, extract values from APIs or pages, reuse them in later commands and persist a browser session. These mechanisms have different scopes and lifetimes.
+
+| Requirement | Value |
+| --- | --- |
+| Engine | OS or Cloud |
+| Browser | Chromium, Firefox or WebKit |
+| Application | Shared local demo |
+| Cloud account | Optional |
+
+Complete the [shared setup](../README.md), including `EXAMPLE_LABEL="Workflow fixture"`, and keep the same demo-server process running for the session examples.
+
+## Generate once, extract and reuse
+
+[setup.first.flow](flows/setup.first.flow) sends generated data to the demo API, extracts it and reuses it in another API call and the browser:
+
+```flow
+Feature: Generated and extracted variable reuse
+Scenario: Preserve one generated value across API and UI
+Given "Generate data once and extract the response"
+  flow.post "/api/echo" with reqBody;
+  """
+  {
+    "email": "$randomEmail@example.test",
+    "label": "{{env.EXAMPLE_LABEL}}"
+  }
+  """
+  flow.extract resBody "email" as "rememberedEmail";
+  flow.extract resBody "label" as global "sharedLabel";
+When "The generated value is reused in a second API request"
+  flow.post "/api/echo" with reqBody;
+  """
+  {
+    "email": "@rememberedEmail"
+  }
+  """
+And "Generation did not silently create another value"
+  flow.expect resBody "email" equals "@randomEmail@example.test";
+When "Reuse the extraction in a browser field"
+  flow.open "/reuse";
+  flow.type input "Selected value" "@rememberedEmail";
+  flow.click button "Apply value";
+Then "The browser received the exact value"
+  flow.expect text "Selected @rememberedEmail";
+```
+
+`$randomEmail` generates a value; `@randomEmail` reuses the last generated value for that generator in this file. The suffix is literal: `$randomEmail@example.test` and `@randomEmail@example.test` keep the same complete address. A later `$randomEmail` call generates another value.
+
+`flow.extract ... as "rememberedEmail"` stores a file-local extraction. `as global "sharedLabel"` makes the extraction explicitly process-global.
+
+[reuse.flow](flows/reuse.flow) reads that global value from the next file:
+
+```flow
+Feature: Explicit process-global reuse
+Scenario: Read a global extraction in the next file
+Given "Open the reuse form"
+  flow.open "/reuse";
+When "Use the explicitly global label"
+  flow.type input "Selected value" "@global[sharedLabel]";
+  flow.click button "Apply value";
+Then "The environment value survived the file boundary"
+  flow.expect text "Selected Workflow fixture";
+```
+
+Run the two files together, sequentially:
+
+```sh
+npx flowstride run workflow-examples/variables-and-reuse/flows --workers 1 --ci
+```
+
+The `.first.flow` setup executes before the ordinary file. Expected: generated-email equality, exact UI reuse and `Selected Workflow fixture` in the second file. Both files pass.
+
+## Scope and lifetime
+
+| Mechanism | Use | Lifetime |
+| --- | --- | --- |
+| `{{env.NAME}}` | Application URLs, configuration values and private test credentials | Supplied by the process and loaded environment files |
+| `$randomEmail` / `@randomEmail` | Generate a value / reuse its last remembered value | Generator memory resets for each file |
+| `@rememberedEmail` | Reuse a local extraction | Current flow file, including later scenarios in that file |
+| `@global[sharedLabel]` | Reuse an explicit global extraction | Current worker process; not shared memory across workers or machines |
+| Browser `localStorage` / `sessionStorage` | Application browser storage | Browser profile/origin and application lifecycle |
+| Persisted named session | Restore a saved browser snapshot in a later run | Local `.flowstride` session data until replaced/removed |
+
+Keep the global example at one worker. A Cloud parallel run can use several processes; a global variable is not a shared cross-worker database. A later CLI invocation starts a new process and does not inherit these global variables. Undefined global references fail explicitly.
+
+## Save and restore browser state
+
+Run the [session-saving flow](sessions/save.flow):
+
+```sh
+npx flowstride run workflow-examples/variables-and-reuse/sessions/save.flow --ci
+```
+
+It creates a demo user, signs in through the UI and uses:
+
+```flow
+flow.save session "workflow-reader" persist;
+```
+
+Then run [restore.flow](sessions/restore.flow) in a fresh CLI invocation:
+
+```sh
+npx flowstride run workflow-examples/variables-and-reuse/sessions/restore.flow --ci
+```
+
+That file uses:
+
+```flow
+Feature: Restore a persisted account
+Scenario: Restore in a fresh process
+Given "Load the saved browser state"
+ flow.use session "workflow-reader";
+When "Open the account page"
+ flow.open "/dashboard";
+Then "Cookies and both storage types are restored"
+ flow.expect visible "Welcome, Workflow Reader";
+ flow.expect attribute "#storage" "data-mode" "signed-in";
+ flow.expect attribute "#storage" "data-session" "active";
+```
+
+Expected: the signed-in account is visible and the stored local/session values are available before the dashboard's startup code reads them. Keep the demo server running: restarting it removes the backend user even if the browser snapshot still exists.
+
+A snapshot captures cookies and Web Storage for the selected browser profile. Storage restoration is restricted to its matching top-level HTTP(S) origin and seeds the saved values once; later app changes and reloads are preserved. It does not inject saved storage into another site's frame.
+
+Use a current snapshot with saved origin metadata. Legacy snapshots lacking an origin prefer the configured application base URL, then an available current application page. Configure the intended `BASE_URL` before restoring a legacy record. Persisted sessions contain credentials and belong outside version control.
+
+Saving a session does not create a second live user. Use [named browser profiles](../../../NATIVE_BROWSER.md#separate-users-in-one-test) when customer and admin must stay independently signed in. Saved browser state is also separate from application backend data and arbitrary flow variables.
+
+## Deliberate failures
+
+```sh
+npx flowstride run workflow-examples/variables-and-reuse/negative/wrong-reused-value.flow --ci
+```
+
+This reuses the extraction but expects a different UI value, so its assertion must fail and exit nonzero.
+
+To observe process isolation, run `flows/reuse.flow` by itself in a new CLI invocation. It has no setup in that process, so `@global[sharedLabel]` must be undefined. This is a setup failure rather than a successful assertion; inspect the error and incomplete steps.
+
+The [full variable reference](https://docs.flowstride.io/flow-language/getting-started/variables) covers aliases and additional examples. General `{{env.NAME}}` substitution belongs in command string values; do not assume every JSON configuration field performs the same substitution.

package/examples/native-workflows/variables-and-reuse/flows/reuse.flow

@@ -0,0 +1,9 @@
+Feature: Explicit process-global reuse
+Scenario: Read a global extraction in the next file
+Given "Open the reuse form"
+  flow.open "/reuse";
+When "Use the explicitly global label"
+  flow.type input "Selected value" "@global[sharedLabel]";
+  flow.click button "Apply value";
+Then "The environment value survived the file boundary"
+  flow.expect text "Selected Workflow fixture";

package/examples/native-workflows/variables-and-reuse/flows/setup.first.flow

@@ -0,0 +1,27 @@
+Feature: Generated and extracted variable reuse
+Scenario: Preserve one generated value across API and UI
+Given "Generate data once and extract the response"
+  flow.post "/api/echo" with reqBody;
+  """
+  {
+    "email": "$randomEmail@example.test",
+    "label": "{{env.EXAMPLE_LABEL}}"
+  }
+  """
+  flow.extract resBody "email" as "rememberedEmail";
+  flow.extract resBody "label" as global "sharedLabel";
+When "The generated value is reused in a second API request"
+  flow.post "/api/echo" with reqBody;
+  """
+  {
+    "email": "@rememberedEmail"
+  }
+  """
+And "Generation did not silently create another value"
+  flow.expect resBody "email" equals "@randomEmail@example.test";
+When "Reuse the extraction in a browser field"
+  flow.open "/reuse";
+  flow.type input "Selected value" "@rememberedEmail";
+  flow.click button "Apply value";
+Then "The browser received the exact value"
+  flow.expect text "Selected @rememberedEmail";

package/examples/native-workflows/variables-and-reuse/negative/wrong-reused-value.flow

@@ -0,0 +1,27 @@
+Feature: Generated and extracted variable reuse
+Scenario: Preserve one generated value across API and UI
+Given "Generate data once and extract the response"
+  flow.post "/api/echo" with reqBody;
+  """
+  {
+    "email": "$randomEmail@example.test",
+    "label": "{{env.EXAMPLE_LABEL}}"
+  }
+  """
+  flow.extract resBody "email" as "rememberedEmail";
+  flow.extract resBody "label" as global "sharedLabel";
+When "The generated value is reused in a second API request"
+  flow.post "/api/echo" with reqBody;
+  """
+  {
+    "email": "@rememberedEmail"
+  }
+  """
+And "Generation did not silently create another value"
+  flow.expect resBody "email" equals "@randomEmail@example.test";
+When "Reuse the extraction in a browser field"
+  flow.open "/reuse";
+  flow.type input "Selected value" "@rememberedEmail";
+  flow.click button "Apply value";
+Then "The browser received the exact value"
+  flow.expect text "Selected impossible@example.test";

package/examples/native-workflows/variables-and-reuse/sessions/restore.flow

@@ -0,0 +1,10 @@
+Feature: Restore a persisted account
+Scenario: Restore in a fresh process
+Given "Load the saved browser state"
+ flow.use session "workflow-reader";
+When "Open the account page"
+ flow.open "/dashboard";
+Then "Cookies and both storage types are restored"
+ flow.expect visible "Welcome, Workflow Reader";
+ flow.expect attribute "#storage" "data-mode" "signed-in";
+ flow.expect attribute "#storage" "data-session" "active";

package/examples/native-workflows/variables-and-reuse/sessions/save.flow

@@ -0,0 +1,29 @@
+Feature: API and browser in one test
+Scenario: Create through API and sign in through UI
+Given "Create a disposable user"
+  flow.post "/api/users" with reqBody;
+  """
+  {
+    "email": "$randomEmail@example.test",
+    "password": "fixture-password",
+    "name": "Workflow Reader"
+  }
+  """
+  flow.extract resBody "id" as "createdId";
+  flow.extract resBody "email" as "createdEmail";
+And "Creation succeeds"
+  flow.expect status "201";
+When "Sign in through the browser"
+  flow.open "/login";
+  flow.type input "Email" "@createdEmail";
+  flow.type input "Password" "fixture-password";
+  flow.click button "Sign in";
+And "The UI shows the created account"
+  flow.expect visible "Welcome, Workflow Reader";
+When "Verify backend state from the same test"
+  flow.get "/api/users/@createdId";
+When "Persist authenticated browser state"
+ flow.save session "workflow-reader" persist;
+Then "The backend recorded the browser login"
+  flow.expect status "200";
+  flow.expect resBody "loginCount" equals "1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowstride",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "An opensource flowfirst test automation framework",
   "workspaces": [
     "packages/flowstride_report"
@@ -11,7 +11,10 @@
     "dist",
     "src/ui/dist",
     "NATIVE_CI.md",
-    "examples/native-game"
+    "examples/native-game",
+    "NATIVE_BROWSER.md",
+    "NATIVE_WORKFLOWS.md",
+    "examples/native-workflows"
   ],
   "bin": {
     "flowstride": "dist/cli/index.js"
@@ -27,10 +30,12 @@
     "verify:candidate": "node scripts/verify-candidate.cjs",
     "test:dashboard:unit": "node --test tests/dashboard/store.test.cjs",
     "test:dashboard": "node --test --test-concurrency=1 tests/dashboard/*.test.cjs",
-    "test:unit": "node --test tests/native/core.test.cjs tests/native/combined.test.cjs tests/native/curl.test.cjs tests/native/upload.test.cjs tests/dashboard/store.test.cjs tests/native/replay.test.cjs tests/dashboard/replay.test.cjs tests/native/assertions-sessions.test.cjs",
-    "test:security": "node --test tests/manual-security.test.cjs tests/native/curl.test.cjs tests/native/combined.test.cjs tests/native/replay.test.cjs tests/native/assertions-sessions.test.cjs",
+    "test:unit": "node --test tests/native/core.test.cjs tests/native/combined.test.cjs tests/native/curl.test.cjs tests/native/upload.test.cjs tests/dashboard/store.test.cjs tests/native/replay.test.cjs tests/dashboard/replay.test.cjs tests/native/assertions-sessions.test.cjs tests/native/capabilities.test.cjs tests/native/browser-selection.unit.test.cjs tests/native/manual-boundary.test.cjs tests/native/storage-hover.test.cjs tests/native/plugin-runtime.test.cjs tests/native/runtime-assertions.test.cjs tests/native/runtime-api-refresh.test.cjs tests/dashboard/report-status.test.cjs tests/dashboard/manual-title.test.cjs tests/native/assertion-results.test.cjs tests/dashboard/assertion-results.test.cjs",
+    "test:security": "node --test tests/manual-security.test.cjs tests/native/curl.test.cjs tests/native/combined.test.cjs tests/native/replay.test.cjs tests/native/assertions-sessions.test.cjs tests/native/capabilities.test.cjs tests/native/browser-selection.unit.test.cjs tests/native/manual-boundary.test.cjs tests/native/storage-hover.test.cjs tests/native/plugin-runtime.test.cjs tests/native/runtime-assertions.test.cjs tests/native/runtime-api-refresh.test.cjs tests/dashboard/report-status.test.cjs tests/dashboard/manual-title.test.cjs tests/dashboard/manual-history.browser.test.cjs tests/native/assertion-results.test.cjs tests/dashboard/assertion-results.test.cjs",
     "test:replay": "node --test tests/native/replay.test.cjs tests/dashboard/replay.test.cjs tests/dashboard/curl.browser.test.cjs",
-    "test:assertions-sessions": "node --test --test-concurrency=1 tests/native/assertions-sessions*.test.cjs"
+    "test:assertions-sessions": "node --test --test-concurrency=1 tests/native/assertions-sessions*.test.cjs",
+    "test:capabilities": "node --test --test-concurrency=1 tests/native/capabilities*.test.cjs",
+    "test:examples": "node --test --test-concurrency=1 tests/native/workflow-examples.test.cjs"
   },
   "keywords": [
     "automation",
@@ -44,28 +49,37 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
+    "@axe-core/playwright": "4.14.0",
     "@inquirer/prompts": "^7.10.1",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitejs/plugin-vue": "6.0.10",
     "axios": "^1.20.0",
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
+    "dom-accessibility-api": "0.7.1",
     "dotenv": "^17.4.2",
     "open": "^11.0.0",
     "ora": "^5.4.1",
     "playwright": "1.59.1",
+    "playwright-core": "1.59.1",
     "playwright-extra": "^4.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "sanitize-html": "2.18.1",
     "tar": "^7.5.22",
     "ts-node": "^10.9.2",
     "undici": "^7.30.1",
+    "vite": "8.3.5",
     "ws": "^8.22.0",
-    "sanitize-html": "2.18.1",
-    "zod": "4.4.3"
+    "zod": "4.6.7",
+    "typescript": "5.9.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "@types/sanitize-html": "2.16.2",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3",
-    "@types/sanitize-html": "2.16.2"
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "three": "0.186.1"
   },
   "optionalDependencies": {
     "@rolldown/binding-darwin-arm64": "^0.15.1"