flowstride 1.0.21 → 1.0.22

package/dist/security/localWorkspace.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalWorkspaceRequest = isLocalWorkspaceRequest;
+const localDashboard_1 = require("./localDashboard");
+/** Bind the manual workspace browser boundary to the actual loopback listener. */
+function isLocalWorkspaceRequest(host, origin, localPort, fetchSite) {
+    if (!Number.isInteger(localPort) || !localPort || localPort < 1 || localPort > 65535)
+        return false;
+    if (!(0, localDashboard_1.isLocalDashboardRequest)(host, origin) || fetchSite === 'cross-site')
+        return false;
+    try {
+        return Number(new URL(`http://${host}`).port) === localPort;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/security/redaction.js

@@ -33,7 +33,7 @@ function redactPayload(value, secrets = [], depth = 0) {
         return value.map(item => redactPayload(item, secrets, depth + 1));
     if (!value || typeof value !== 'object')
         return value;
-    if (Buffer.isBuffer(value))
+    if (globalThis.Buffer?.isBuffer(value))
         return '[binary]';
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sensitive.test(key) ? '[REDACTED]' : redactPayload(item, secrets, depth + 1)]));
 }

package/dist/types/index.d.ts

@@ -105,6 +105,7 @@ export interface FlowstrideSDK {
         get: (url: string, headers?: Record<string, string>) => Promise<any>;
         post: (url: string, body: any, headers?: Record<string, string>) => Promise<any>;
         put: (url: string, body: any, headers?: Record<string, string>) => Promise<any>;
+        patch: (url: string, body: any, headers?: Record<string, string>) => Promise<any>;
         delete: (url: string, headers?: Record<string, string>) => Promise<any>;
     };
     ui: {
@@ -116,6 +117,8 @@ export interface FlowstrideSDK {
     state: {
         get: (key: string) => any;
         set: (key: string, value: any) => void;
+        delete: (key: string) => void;
+        clear: () => void;
     };
     env: {
         get: (key: string) => string | undefined;

package/examples/native-workflows/README.md

@@ -0,0 +1,144 @@
+# Run the core workflow examples
+
+These examples accompany [Core Flowstride workflows](../../NATIVE_WORKFLOWS.md). The shared application runs on your computer and stores disposable data in memory. It sends no email and performs no speech recognition. The email-OTP and real-transcription templates explain how to use your own authorized application and services.
+
+## 1. Install through npm
+
+Use Node.js 22.12 or newer. In a new project:
+
+```sh
+mkdir flowstride-workflows
+cd flowstride-workflows
+npm init -y
+npm i flowstride
+npx flowstride init
+npx flowstride install chromium
+```
+
+`init` creates the workspace. The explicit browser-install command installs the Chromium build matching the selected engine. The chapters below run their own named example files; any starter file generated under `flows/` is separate.
+
+Copy the examples shipped by the installed package into your project. This keeps fixture edits, sessions and reports in your workspace:
+
+```sh
+cp -R node_modules/flowstride/examples/native-workflows workflow-examples
+```
+
+On PowerShell, the equivalent copy is:
+
+```powershell
+Copy-Item -Recurse node_modules/flowstride/examples/native-workflows workflow-examples
+```
+
+Use a fresh `workflow-examples` destination. In an existing project, preserve your configuration and fixtures instead of overwriting them.
+
+## 2. Configure the local application URL
+
+Create a project-root `.env` file, or add these values to the existing file:
+
+```dotenv
+BASE_URL=http://127.0.0.1:4107
+EXAMPLE_LABEL="Workflow fixture"
+```
+
+OS and Cloud load `.env` automatically for a run. `BASE_URL` supplies the base for relative browser and API URLs. You can alternatively set `baseUrl` in `flowstride.config.json`; `BASE_URL` takes precedence.
+
+For example, `flow.open "/orders";` and `flow.post "/api/users" ...` use the same configured application. String values inside `.flow` commands can use `{{env.NAME}}`. General environment-template substitution is not performed throughout the JSON configuration file.
+
+Ensure your project's `.gitignore` includes:
+
+```gitignore
+node_modules/
+.env
+.env.*
+!.env.example
+.flowstride/
+flowstride-artifacts/
+```
+
+Share placeholder values in `.env.example`. Keep real credentials in local configuration or CI secrets.
+
+## 3. Start the demo application
+
+In a separate terminal, from the project root:
+
+```sh
+node workflow-examples/shared/server.mjs
+```
+
+Leave it running. It prints `http://127.0.0.1:4107`; open that address to see the example routes. It listens only on loopback and is a demonstration fixture, not a production authentication service.
+
+If the port is occupied, select another port and update `BASE_URL` to match:
+
+```sh
+FLOWSTRIDE_EXAMPLE_PORT=4108 node workflow-examples/shared/server.mjs
+```
+
+PowerShell:
+
+```powershell
+$env:FLOWSTRIDE_EXAMPLE_PORT = "4108"
+node workflow-examples/shared/server.mjs
+```
+
+Restarting the app clears its demo users and profile changes. A saved browser session does not restore the app's in-memory database.
+
+## 4. Run a named example
+
+In your other terminal:
+
+```sh
+npx flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow
+```
+
+Interactive execution opens the local dashboard. For headless execution, a process exit code and retained evidence:
+
+```sh
+npx flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow --ci
+```
+
+A successful run exits with code `0`. Deliberate failures exit nonzero. Read `flowstride-artifacts/summary.json` and `junit.xml`; the summary identifies its unique `run-*` evidence directory. Failed assertions retain their screenshot and video when recording is enabled.
+
+Read an individual step's `error` as well as the suite-level `errors`: an assertion failure can appear on the failed step while the suite-error array is empty.
+
+## 5. Choose browsers or Cloud
+
+```sh
+npx flowstride install chromium firefox webkit
+npx flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow --browser firefox --ci
+npx flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow --browser webkit --ci
+```
+
+Chromium is the default. Firefox and WebKit run the API/UI, iframe, table and variable examples. Audio-file microphone injection requires Chromium. Use `--headed` to see the test application's browser window during an interactive run.
+
+For Cloud, connect with `npx flowstride login`, accept the authenticated installation when offered, then use the same commands. Private engine hosting and installation details are handled by the authenticated channel.
+
+## CI application startup
+
+Flowstride can own the local application's lifecycle. Stop the manually started demo server first, then use a project configuration such as:
+
+```json
+{
+  "testDir": "workflow-examples/api-and-ui/flows",
+  "timeout": 10000,
+  "cloudSync": false,
+  "webServer": {
+    "command": "node workflow-examples/shared/server.mjs",
+    "url": "http://127.0.0.1:4107",
+    "timeout": 10000
+  }
+}
+```
+
+Keep `BASE_URL` set in the environment or `.env`. Flowstride starts the configured app, checks readiness, runs the tests and stops the app afterward. It refuses to adopt a readiness URL that is already serving.
+
+Use `npm ci` and matching browser installation on your CI runner. [NATIVE_CI.md](../../NATIVE_CI.md) covers workflow generation and artifact retention. Keep intentional failures and service-dependent templates out of the passing CI target.
+
+## Chapters
+
+- [API + UI](api-and-ui/README.md)
+- [API + UI + email OTP](api-ui-otp/README.md)
+- [iFrames](iframes/README.md)
+- [Audio-to-text](audio-to-text/README.md)
+- [Tables and cells](tables-and-cells/README.md)
+- [Variables and saved sessions](variables-and-reuse/README.md)
+- [Manual testing](manual-testing/README.md)

package/examples/native-workflows/api-and-ui/README.md

@@ -0,0 +1,80 @@
+# API + UI in the same test
+
+One `.flow` scenario can create data through an API, extract the response, interact with the browser and make another API request to verify the outcome. No custom runner is needed.
+
+| Requirement | Value |
+| --- | --- |
+| Engine | OS or Cloud |
+| Browser | Chromium, Firefox or WebKit |
+| Application | Shared local demo, running in another terminal |
+| Cloud account | Optional for this example |
+
+Complete the [shared setup](../README.md), including `.env` and the running application.
+
+## Complete example
+
+[Read the runnable file](flows/api-and-ui.flow). It creates a disposable demo user, reuses its returned email in the UI and checks the recorded login count:
+
+```flow
+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";
+Then "The backend recorded the browser login"
+  flow.expect status "200";
+  flow.expect resBody "loginCount" equals "1";
+```
+
+`@createdId` and `@createdEmail` are extracted values available later in this file. The browser's UI login changes the backend; the final API assertion verifies that change.
+
+Use `And` for an intermediate assertion block. `Then` closes the scenario, so put the final outcome there rather than adding more steps after it.
+
+## Run and inspect
+
+From the project root:
+
+```sh
+npx flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow --ci
+```
+
+Expected: HTTP registration status `201`, visible `Welcome, Workflow Reader`, backend `loginCount` equal to `1`, and a passed summary with process exit code `0`.
+
+Try another browser with `--browser firefox` or `--browser webkit`. The same test commands work after connecting Cloud.
+
+## Deliberate failure
+
+```sh
+npx flowstride run workflow-examples/api-and-ui/negative/wrong-backend-state.flow --ci
+```
+
+That file expects `loginCount` to equal `99`. The browser login still occurs, but the final assertion must fail and the process must exit nonzero. Inspect the failed step, screenshot and video. A completed HTTP request is not proof of HTTP success: use an explicit status/body assertion.
+
+## Adapt to your application
+
+Replace the API routes, request fields, response extraction paths and UI labels with your application's contract. Keep expected status codes and business outcomes explicit. Use disposable test accounts and provide an application-appropriate cleanup path when the backend stores data persistently.
+
+The demo intentionally uses minimal local test authentication. Your application may require CSRF handling, application credentials or a privileged setup account. A Flowstride Cloud developer token authorizes Cloud services; application API authorization is configured separately.
+
+Variables are shared through Flowstride's variable mechanisms; browser cookies and direct API authentication are separate state. Use the [saved-session guide](../variables-and-reuse/README.md#save-and-restore-browser-state) when you need a browser snapshot, and configure API request headers explicitly for your application's protected endpoints.
+
+For an email challenge after login, continue with [API + UI + OTP](../api-ui-otp/README.md).

package/examples/native-workflows/api-and-ui/flows/api-and-ui.flow

@@ -0,0 +1,27 @@
+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";
+Then "The backend recorded the browser login"
+  flow.expect status "200";
+  flow.expect resBody "loginCount" equals "1";

package/examples/native-workflows/api-and-ui/negative/wrong-backend-state.flow

@@ -0,0 +1,27 @@
+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";
+Then "The backend recorded the browser login"
+  flow.expect status "200";
+  flow.expect resBody "loginCount" equals "99";

package/examples/native-workflows/api-ui-otp/README.md

@@ -0,0 +1,140 @@
+# API + UI + email OTP
+
+FlowMail retrieves an OTP delivered to a supported test inbox and stores it in a flow variable. The same test can register through your application's API, sign in through its UI, enter the code and assert successful authentication.
+
+| Requirement | Value |
+| --- | --- |
+| Engine | Cloud; `flow.mail.getOtp` is a Cloud service command |
+| Browser | Chromium, Firefox or WebKit for ordinary browser interactions |
+| Cloud access | Authenticated developer token and available workspace FlowMail allowance |
+| Application | An authorized test application that actually sends email OTP |
+| Inbox | An address supported by FlowMail, using `@flowstridemail.com` |
+
+Cloud includes free accounts. FlowMail allowances depend on the workspace plan and current usage. This chapter's templates require your application's real routes and selectors; the shared local demo does not send email.
+
+## Connect Cloud
+
+Follow the normal [npm setup](../README.md), then:
+
+```sh
+npx flowstride login
+```
+
+Use your developer token at the prompt and accept authenticated engine installation when offered. In CI, use the `FLOWSTRIDE_TOKEN` secret and the normal Cloud setup described in [NATIVE_CI.md](../../../NATIVE_CI.md).
+
+## Register, sign in and verify
+
+[api-ui-otp.flow](templates/api-ui-otp.flow) is a complete application template. Its contract is:
+
+- Registration accepts the shown fields, returns `201` and a `userId`, and leaves the account active for sign-in.
+- The login form has Email, Password and Login targets.
+- Login triggers an email to the generated address.
+- The challenge has an Enter 6-digit OTP input and Verify OTP button.
+- `Logout` is visible only after authentication completes.
+
+Adapt these fields, selectors and expected results to your application. In your private `.env`, configure:
+
+```dotenv
+SIGNUP_URL=https://your-test-application.example/api/register
+LOGIN_URL=https://your-test-application.example/login
+```
+
+The template contains the full API-to-UI journey:
+
+```flow
+Feature: Register through an application API and verify an email OTP in the UI
+
+  Scenario: Complete an email-verified sign-in with a disposable account
+    Given "The application creates an active test account"
+      flow.post "{{env.SIGNUP_URL}}" with reqBody;
+      """
+      {
+        "firstName": "Example",
+        "lastName": "Reader",
+        "email": "$randomEmail@flowstridemail.com",
+        "password": "$randomPassword"
+      }
+      """
+      flow.extract resBody "userId" as "newUserId";
+      flow.expect status "201";
+
+    When "Open the application's sign-in form"
+      flow.open "{{env.LOGIN_URL}}";
+      flow.type input "Email" "@randomEmail@flowstridemail.com";
+      flow.type input "Password" "@randomPassword";
+      flow.click button "Login";
+
+    When "Retrieve the delivered code through FlowMail"
+      flow.mail.getOtp "@randomEmail@flowstridemail.com" into "loginOtp";
+
+    When "Submit the retrieved code"
+      flow.type input "Enter 6-digit OTP" "@loginOtp";
+      flow.click button "Verify OTP";
+
+    Then "The application confirms successful authentication"
+      flow.expect visible "Logout";
+```
+
+`$randomEmail` and `$randomPassword` generate values; `@randomEmail` and `@randomPassword` reuse their remembered values in this file. The address suffix must stay consistent between registration, UI sign-in and inbox polling.
+
+Run the adapted template explicitly:
+
+```sh
+npx flowstride run workflow-examples/api-ui-otp/templates/api-ui-otp.flow --ci
+```
+
+Expected: registration succeeds, the code is retrieved and entered, the application confirms sign-in, and the process exits `0`.
+
+### Applications requiring approval
+
+If registration creates a pending account, add your application's authorized approval step before browser sign-in. For an application whose approval API uses a bearer token, an example block is:
+
+```flow
+When "Approve the test account using application authorization"
+  flow.post "{{env.APPROVAL_URL}}"
+    with reqHeader "Authorization" "Bearer {{env.APPROVAL_TOKEN}}"
+    with reqBody;
+  """
+  {
+    "userId": "@newUserId"
+  }
+  """
+
+And "The application accepted approval"
+  flow.expect status "200";
+```
+
+Use your application's actual authorization scheme and verify the resulting active state. A cookie-based approver session needs its own application setup. A `401` or `403` at this step prevents the test from reaching OTP and must be resolved as an application prerequisite.
+
+## Use an existing account
+
+For a preapproved account, adapt [existing-account-otp.flow](templates/existing-account-otp.flow) instead. Configure:
+
+```dotenv
+LOGIN_URL=https://your-test-application.example/login
+OTP_TEST_EMAIL=your-supported-test-address@flowstridemail.com
+OTP_TEST_PASSWORD=replace-with-the-application-test-password
+```
+
+```sh
+npx flowstride run workflow-examples/api-ui-otp/templates/existing-account-otp.flow --ci
+```
+
+The chosen account must require an email OTP challenge. An account that signs in directly does not exercise email delivery or retrieval.
+
+## Negative checks and diagnosis
+
+For a deterministic assertion failure, change the final expected login marker to a value your application never displays. The run must fail even after code retrieval succeeds. To test invalid-code handling, use a code known to be invalid for that request and assert the application's rejection message; a fixed six-digit value is not guaranteed to be wrong.
+
+FlowMail polls up to ten times with delays. Authentication or permission rejection stops the lookup; an inbox with no matching code eventually times out. Set a suitable test timeout for delivery and your application's processing time.
+
+| Result | Check |
+| --- | --- |
+| No Cloud authentication | Run `npx flowstride login` or configure the CI secret |
+| Permission/allowance rejection | Check workspace access, token validity and FlowMail usage |
+| Approval returns `401`/`403` | Supply authorized application setup before sign-in |
+| No email arrives | Confirm the application actually sends to the same supported address |
+| Login succeeds without challenge | Use an account that requires OTP |
+| Code retrieved, login still fails | Inspect application expiry, validation and the final UI outcome |
+
+Code retrieval alone is not a passed authentication test. Keep the final application assertion, and isolate account creation/mail side effects when designing retries.

package/examples/native-workflows/api-ui-otp/templates/api-ui-otp.flow

@@ -0,0 +1,31 @@
+Feature: Register through an application API and verify an email OTP in the UI
+
+  Scenario: Complete an email-verified sign-in with a disposable account
+    Given "The application creates an active test account"
+      flow.post "{{env.SIGNUP_URL}}" with reqBody;
+      """
+      {
+        "firstName": "Example",
+        "lastName": "Reader",
+        "email": "$randomEmail@flowstridemail.com",
+        "password": "$randomPassword"
+      }
+      """
+      flow.extract resBody "userId" as "newUserId";
+      flow.expect status "201";
+
+    When "Open the application's sign-in form"
+      flow.open "{{env.LOGIN_URL}}";
+      flow.type input "Email" "@randomEmail@flowstridemail.com";
+      flow.type input "Password" "@randomPassword";
+      flow.click button "Login";
+
+    When "Retrieve the delivered code through FlowMail"
+      flow.mail.getOtp "@randomEmail@flowstridemail.com" into "loginOtp";
+
+    When "Submit the retrieved code"
+      flow.type input "Enter 6-digit OTP" "@loginOtp";
+      flow.click button "Verify OTP";
+
+    Then "The application confirms successful authentication"
+      flow.expect visible "Logout";

package/examples/native-workflows/api-ui-otp/templates/existing-account-otp.flow

@@ -0,0 +1,20 @@
+Feature: Email OTP for an existing application test account
+
+  Scenario: Authenticate an account that requires email OTP
+    Given "An active OTP-enabled test account"
+      flow.open "{{env.LOGIN_URL}}";
+
+    When "Sign in with the application credentials"
+      flow.type input "Email" "{{env.OTP_TEST_EMAIL}}";
+      flow.type input "Password" "{{env.OTP_TEST_PASSWORD}}";
+      flow.click button "Login";
+
+    When "Read the code delivered to the supported test inbox"
+      flow.mail.getOtp "{{env.OTP_TEST_EMAIL}}" into "loginOtp";
+
+    When "Complete verification"
+      flow.type input "Enter 6-digit OTP" "@loginOtp";
+      flow.click button "Verify OTP";
+
+    Then "The application confirms the login"
+      flow.expect visible "Logout";

package/examples/native-workflows/audio-to-text/README.md

@@ -0,0 +1,131 @@
+# Test audio-to-text workflows
+
+Flowstride supplies prerecorded audio to the browser's microphone, drives recording controls and checks the transcript displayed by your application. Your application's speech-to-text service performs recognition.
+
+| Requirement | Value |
+| --- | --- |
+| Engine | OS or Cloud |
+| Browser | Chromium for audio-file microphone injection |
+| Local demo | Included PCM WAV, real microphone capture and a simulated transcript response |
+| Real transcription | Your own authorized recording application, service and spoken WAV fixture |
+
+Complete the [shared setup](../README.md). Install the matching Chromium explicitly if needed:
+
+```sh
+npx flowstride install chromium
+```
+
+## 1. Run the self-contained microphone demo
+
+The included [microphone-tone.wav](fixtures/microphone-tone.wav) is a short generated tone. The demo requests `getUserMedia`, measures actual microphone input and produces a deterministic transcript-like response when it detects a signal. This checks input delivery, recording controls, waiting and assertions; it is not a speech-recognition accuracy test.
+
+[microphone-demo.flow](flows/microphone-demo.flow):
+
+```flow
+Feature: Microphone and transcript UI fixture
+Scenario: Capture a known microphone signal
+Given "Configure a PCM WAV before browser startup"
+  flow.injectAudio "workflow-examples/audio-to-text/fixtures/microphone-tone.wav";
+  flow.browser.permissions {
+    "permissions": [
+      "microphone"
+    ]
+  };
+  flow.open "/audio";
+When "Start recording"
+  flow.click button "Start recording";
+  flow.expect visible "Recording active";
+When "Allow the fixture audio to play and stop"
+  flow.waitForPipeline;
+  flow.click button "Stop recording";
+Then "The simulated transcription result is displayed"
+  flow.expect transcript contains "Fixture transcript: audio received.";
+  flow.assert.that {
+    "selector": "#transcript",
+    "condition": "text",
+    "value": "Fixture transcript: audio received."
+  };
+```
+
+```sh
+npx flowstride run workflow-examples/audio-to-text/flows/microphone-demo.flow --browser chromium --ci
+```
+
+Expected: recording becomes active, non-silent microphone input is captured, recording stops, and the displayed result is `Fixture transcript: audio received.`. The run exits `0`.
+
+The fixture path is literal and relative to the project root after the shared copy step. The engine reads the first literal audio fixture before browser startup. It does not resolve flow variables in that pre-launch path or hot-swap recordings during an active browser session. Run different audio fixtures in separate invocations.
+
+## 2. Confirm a wrong transcript fails
+
+```sh
+npx flowstride run workflow-examples/audio-to-text/negative/wrong-transcript.flow --browser chromium --ci
+```
+
+This captures audio but expects a phrase the demo never produces. It must fail and exit nonzero. Inspect its failed assertion and media.
+
+Firefox and WebKit reject `flow.injectAudio` explicitly. Keep audio cases in a Chromium job instead of adding them indiscriminately to a three-browser matrix.
+
+## 3. Adapt to a real transcription service
+
+Use [real-transcription.flow](templates/real-transcription.flow) with your recording application. Put a known spoken recording at the literal project path `fixtures/voice-note.wav`. Use an uncompressed PCM WAV with a conventional 44-byte header; changing a file extension does not convert its audio format.
+
+Configure private application values:
+
+```dotenv
+TRANSCRIPTION_URL=https://your-test-application.example/record
+EXPECTED_TRANSCRIPT="the known words spoken in the recording"
+```
+
+The template is:
+
+```flow
+Feature: Verify a real application's speech transcription
+
+  Scenario: Record known spoken audio and check the resulting transcript
+    Given "A spoken PCM WAV and an authorized recording page"
+      flow.injectAudio "fixtures/voice-note.wav";
+      flow.browser.permissions {
+        "permissions": ["microphone"]
+      };
+      flow.open "{{env.TRANSCRIPTION_URL}}";
+
+    When "Start the application's recording"
+      flow.click button "Start recording";
+      flow.expect visible "Recording active";
+
+    When "Allow the audio clip to play and stop recording"
+      flow.waitForPipeline;
+      flow.click button "Stop recording";
+
+    Then "The new transcript contains the expected spoken words"
+      flow.assert.that {
+        "selector": "#transcript",
+        "condition": "containsText",
+        "value": "{{env.EXPECTED_TRANSCRIPT}}",
+        "timeout": 60000
+      };
+```
+
+Adapt the recording buttons, recording-state label and transcript selector to your application. If authentication is required, add the normal application login or restore a saved browser session before opening the recording page. The application must have a working transcription service and suitable access to it.
+
+```sh
+npx flowstride run workflow-examples/audio-to-text/templates/real-transcription.flow --browser chromium --ci
+```
+
+Expected: the application receives the spoken audio and the **newly produced** transcript contains the known phrase. This is the service-backed check; the local tone demo cannot establish that result.
+
+## Timing and comparison
+
+| Command | Behavior |
+| --- | --- |
+| `flow.injectAudio` | Configures the file used as Chromium microphone input |
+| `flow.browser.permissions` | Grants microphone permission to the current browser profile |
+| `flow.waitForPipeline` | Estimates a wait from the WAV header, approximately the clip duration plus a half second |
+| `flow.expect transcript contains` | Polls rendered page-body text after lowercasing, removing punctuation and collapsing whitespace |
+| `flow.assert.that` with `selector` | Checks the specific result element and supports an explicit timeout |
+
+`flow.waitForPipeline` does not observe an upload, server job or actual playback completion. Assert the recording state and final application result separately. Browser video alone does not prove microphone input or transcription succeeded.
+
+The transcript helper normalizes ASCII word characters and searches the page body. Static example text or old transcripts can satisfy it. Clear old results and prefer a scoped assertion for the new transcript, especially for accented/non-Latin text. If the result is in an input/textarea, use the native `value` condition rather than `text`.
+
+Use a browser-trusted origin such as localhost or HTTPS. Check microphone permission, fixture format, capture start/stop timing and service latency when diagnosing failures. Cloud can run these same browser commands; recording or transcription service credentials remain application prerequisites.