Anatomy of a flow

If the agent generated a flow for you and you want to understand what it produced, here’s what each part does — and how those same parts extend once you’re testing the same behavior on more than one platform. If your team has written Playwright or Appium tests before, QA Wolf flows will look familiar. The selectors, interactions, and assertions work the same way. What’s different is the wrapper around them. Every flow is wrapped in flow() from the @qawolf/flows package — it tells the runner what to run, where to run it, and which runtime objects to inject into the callback.

AAA framework

QA Wolf flows follow the Arrange, Act, Assert (AAA) format.

Arrange — sets up state before the interaction.
Act — performs the interaction being tested.
Assert — verifies the expected outcome.

export default flow(
  "Complete checkout",
  { target: "Web - Chrome", launch: true },
  async ({ page, test }) => {
    await test("arrange", async () => {
      //--------------------------------
      // Arrange:
      //--------------------------------
      await page.goto(process.env.BASE_URL);
    });

    await test("act", async () => {
      //--------------------------------
      // Act:
      //--------------------------------
      await page.fill("[data-testid='email']", "test@example.com");
      await page.click("[data-testid='submit']");
    });

    await test("assert", async () => {
      //--------------------------------
      // Assert:
      //--------------------------------
      await expect(page).toHaveURL(`${process.env.BASE_URL}/confirmation`);
    });
  },
);

iOS and Android use driver.$(...) calls instead of page calls.

Import statement

import { flow, expect } from "@qawolf/flows/web";

import { flow, expect } from "@qawolf/flows/ios";

import { flow, expect } from "@qawolf/flows/android";

import { flow } from "@qawolf/flows/cli";

For web flows, always import expect from @qawolf/flows/web — not from @playwright/test, which causes assertions to bypass QA Wolf’s reporting. iOS, Android, and Node flows don’t have this pitfall: expect is wired to the QA Wolf runner automatically.

Flow wrapper

export default flow(
  "Name shown in QA Wolf",
  { target: "Web - Chrome", launch: true },
  async ({ page }) => {
    // test steps go here
  },
);

Name — what this flow is called in your results, bug reports, and QA Wolf dashboard. Make it descriptive enough that a failing flow name tells you where to look.
Configuration — specifies where the flow runs and how it starts. Pass a plain target string to name the browser, device, or environment, or pass an object with target and launch to configure startup simultaneously — see Target literals for the exact matching rule and the list of values.
Callback — the async function containing your test logic. What it receives depends on the launch style and platform (see below).

Launch styles

Style	When to use
`launch: true`	Most flows — default startup, no configuration needed
Options object	Startup options are known up front — e.g., persistent browser context
Explicit `launch()`	Startup depends on runtime logic — e.g., branching on an environment variable

Declarative launch — recommended

Pass launch: true to use the default startup, or pass an options object to customize it. Either way, QA Wolf starts the browser or app before your callback runs, and the callback receives the platform object ready to use.

If you’ve used Playwright directly, this is the equivalent of calling await browser.launch() — QA Wolf handles that setup for you, so your callback starts with a ready-to-use page.

export default flow(
  "Sign in",
  { target: "Web - Chrome", launch: true },
  async ({ page, test }) => {
    await test("navigate to sign in", async () => {
      await page.goto(process.env.BASE_URL);
    });
  },
);

export default flow(
  "Sign in",
  { target: "iOS - iPhone 15 (iOS 26)", launch: true },
  async ({ driver, test }) => {
    await test("launch app", async () => {
      // driver is ready to use
    });
  },
);

export default flow(
  "Sign in",
  { target: "Android - Pixel 9", launch: true },
  async ({ driver, test }) => {
    await test("launch app", async () => {
      // driver is ready to use
    });
  },
);

Pass an options object instead of true when you need to customize startup, such as reusing a browser profile. See the Web API Reference for the full list of options.

export default flow(
  "Sign in with saved profile",
  {
    target: "Web - Chrome",
    launch: {
      browserContext: "persistent",
      userDataDir: "/tmp/qawolf-profile",
    },
  },
  async ({ page, test }) => {
    await test("navigate to sign in", async () => {
      await page.goto(process.env.BASE_URL);
    });
  },
);

The callback receives a different object depending on the platform:

Platform	Callback receives
Web browser	`page`, `context`, optional `browser`
Web (Electron)	`page`
iOS	`driver` — the Appium/WebdriverIO session for the device
Android	`driver` — the Appium/WebdriverIO session for the device
Node	nothing additional — only `inputs`, `setOutput`, and `test`

Explicit launch — advanced flows only

For advanced cases where the startup depends on runtime logic, you can call launch() explicitly inside the callback. See the Web API Reference for details. For Electron desktop app testing, see Testing Electron apps.

Callback parameters

Every flow callback receives three parameters regardless of platform: inputs — values passed into the flow from outside. Use this to read data published by another flow in the same run. Keys are uppercase by convention, e.g. inputs["EMAIL"]. setOutput(...) — publishes one or more key-value pairs that a later flow in the same run can read via its inputs. Keys are uppercase by convention. You can publish multiple values in a single call:

setOutput("USER_ID", userId, "EMAIL", email);

A consumer flow will not run until its producer has called setOutput. See Passing data between flows for how producers and consumers work together.

test(...) — wraps a named sub-step, grouping actions and assertions under a label that appears in your results. When a step fails, the label tells you exactly where in the flow the failure happened.

export default flow(
  "Create account",
  { target: "Web - Chrome", launch: true },
  async ({ page, inputs, setOutput, test }) => {
    await test("fill registration form", async () => {
      await page.goto(process.env.BASE_URL);
      await page.getByLabel("Email").fill(inputs["EMAIL"]);
      await page.getByRole("button", { name: "Sign up" }).click();
    });

    await test("confirm account created", async () => {
      const userId = await page.getByTestId("user-id").textContent();
      setOutput("USER_ID", userId);
    });
  },
);

Launch-enabled flows also receive the platform object (page, context, browser, or driver) as shown in the launch styles section above. For the full callback context shape, see the API Reference for Web, Android, and iOS.

launch(), device, and platform.target are stubs in the package code, and the runner replaces them at execution time. They only work while a flow is running inside the QA Wolf runner — keep them inside the flow callback, not at the module level.

Module-level code should be limited to imports, constants, and pure helper functions.

platform.target (full API in the Top-Level Reference) lets a single flow branch on the active platform at runtime. Use it sparingly — prefer separate platform-specific flows if you find yourself branching often.

Pure helper functions for platform differences

For platform-specific implementation differences that don’t fit neatly into a Page Object — such as log capture, where iOS uses "safariConsole" and parses JSON while Android uses "browser" with logging preferences — write a helper function that handles the difference internally. The flow calls the helper and stays linear.

// /src/helpers/console-logs-ios.ts
export async function getConsoleLogs(driver: WebdriverIO.Browser) {
  const raw = await driver.getLogs("safariConsole");
  return raw.map((entry) => JSON.parse(entry.message));
}

//helpers/console-logs-android.ts
export async function getConsoleLogs(driver: WebdriverIO.Browser) {
  const raw = await driver.getLogs("browser");
  return raw.map((entry) => entry.message);
}

Keep helper functions like this one pure. As noted above, runtime APIs only work inside the flow callback, not at module level.

Environment variables

Reference environment variables with process.env.VAR_NAME. You typically use them in the Arrange section before any interactions begin.

await page.goto(process.env.BASE_URL);

To set environment variables for your flows, use the environment settings in the QA Wolf platform.

Flow conventions

@qawolf/flows

@qawolf/pom

@qawolf/testkit

@qawolf/emails

@qawolf/cli

Local execution

@qawolf/ci-sdk

REST

AAA framework

Import statement

Flow wrapper

Launch styles

Declarative launch — recommended

Explicit launch — advanced flows only

Callback parameters

Pure helper functions for platform differences

Environment variables

​AAA framework

​Import statement

​Flow wrapper

​Launch styles

​Declarative launch — recommended

​Explicit launch — advanced flows only

​Callback parameters

​Pure helper functions for platform differences

​Environment variables

AAA framework

Import statement

Flow wrapper

Launch styles

Declarative launch — recommended

Explicit launch — advanced flows only

Callback parameters

Pure helper functions for platform differences

Environment variables