Web

@qawolf/flows/web defines web flows and optional explicit launch behavior.

Primary exports

flow(...)
launch(...)
expect
isAnonymous(...)
isPersistent(...)
isElectron(...)
testContextDependencies

It also exports web-specific target, launch, callback context, and flow definition types. Example:

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

export default flow(
  "Open homepage",
  { target: "Web - Chrome", launch: true },
  async ({ page, test }) => {
    await test("open homepage", async () => {
      await page.goto("https://example.com");
      await expect(page).toBeDefined();
    });
  },
);

Target model

Web flows accept web targets only. Use the CLI entry point for Basic.

type WebFlowTargetInput =
  | WebFlowTarget
  | {
      target: WebFlowTarget;
      launch?: false | undefined;
    }
  | {
      target: WebBrowserFlowTarget;
      launch: true | BrowserLaunchOptions;
    }
  | {
      target: WebElectronFlowTarget;
      launch: ElectronFlowLaunchOptions;
    };

Examples:

import { flow, isElectron, isPersistent, launch } from "@qawolf/flows/web";

export const explicitLaunchFlow = flow("Open later", "Web - Chrome", async () => {
  const launchResult = await launch();
  if (isElectron(launchResult)) throw new Error("Expected browser launch");

  const page =
    isPersistent(launchResult)
      ? launchResult.page
      : await launchResult.context.newPage();

  await page.goto("https://example.com");
});

export const launchedFlow = flow(
  "Open immediately",
  { target: "Web - Chrome", launch: true },
  async ({ page, test }) => {
    await test("open page", async () => {
      await page.goto("https://example.com");
    });
  },
);

Launch shapes

Browser launch accepts the generated Playwright browser and context launch options, excluding Playwright’s raw persistentContext and userDataDir fields. QA Wolf adds browserContext, reintroduces userDataDir for persistent launches, and maps those options back to the underlying Playwright shape.

type BrowserLaunchOptions = {
  kind?: "browser";
  browser?: "chrome" | "chromium" | "firefox" | "msedge" | "webkit";
  browserContext?: "incognito" | "persistent";
  userDataDir?: string;

  // Generated Playwright browser and context options are also accepted,
  // except for Playwright's raw persistentContext and userDataDir fields.
  headless?: boolean;
  permissions?: string[];
  geolocation?: {
    latitude: number;
    longitude: number;
    accuracy?: number;
  };
  polyfills?: {
    intlListFormat?: boolean;
  };
  // ...plus other generated browser/context options.
};

type LaunchOptions =
  | BrowserLaunchOptions
  | {
      kind: "electron";
      executablePath: string;
    };

type ElectronFlowLaunchOptions = {
  executablePath: string;
};

type LaunchResult =
  | AnonymousLaunchResult
  | PersistentLaunchResult
  | ElectronLaunchResult;

QA Wolf maps browserContext: "persistent" to Playwright’s persistent context mode. Pass userDataDir with browserContext: "persistent" when you want to reuse a profile directory. Browser example:

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

export default flow(
  "Open with persistent profile",
  "Web - Chrome",
  async () => {
    const { page } = await launch({
      browserContext: "persistent",
      userDataDir: "/tmp/qawolf-profile",
    });

    await page.goto("https://example.com");
  },
);

Electron declarative launch example:

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

export default flow(
  "Open Electron app",
  {
    target: "Electron",
    launch: {
      executablePath: "/Applications/MyApp.app/Contents/MacOS/MyApp",
    },
  },
  async ({ page, test }) => {
    await test("open app", async () => {
      await page.goto("about:blank");
    });
  },
);

Explicit launch(...) calls are not target-typed. Include kind: "electron" and use firstWindowPage from the result:

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

export default flow("Open Electron app", "Web - Chrome", async () => {
  const { firstWindowPage } = await launch({
    kind: "electron",
    executablePath: "/Applications/MyApp.app/Contents/MacOS/MyApp",
  });

  await firstWindowPage.getByRole("button", { name: "Sign in" }).click();
});

Static launch options infer a narrow return type when they determine the result shape:

launch({ browserContext: "persistent" }) returns PersistentLaunchResult
launch({ browserContext: "incognito" }) returns AnonymousLaunchResult
launch({ kind: "electron", executablePath }) returns ElectronLaunchResult
launch() returns the full LaunchResult union because startup depends on the active flow target

Use isAnonymous(...), isPersistent(...), and isElectron(...) to narrow dynamic results before reading shape-specific fields.

Defaults

default kind is browser launch
default browserContext is "incognito"
default browser comes from the flow target
GPU launch behavior is derived from the flow target
Electron declarative launch requires target: "Electron" and executablePath

Example:

import { flow, isElectron, isPersistent, launch } from "@qawolf/flows/web";

export default flow(
  "Use target browser defaults",
  "Web - Firefox",
  async () => {
    const launchResult = await launch();
    if (isElectron(launchResult))
      throw new Error("Expected browser launch");

    const page =
      isPersistent(launchResult)
        ? launchResult.page
        : await launchResult.context.newPage();

    await page.goto("https://example.com");
  },
);

Flow callback context

All web flow callbacks receive:

inputs
setOutput(...)
test(...)

Launch-enabled browser flows also receive:

page
context
optional browser

Electron launch-enabled flows receive the first Electron window as page.

test(...) can be omitted for simple flows where grouping steps into named sub-steps doesn’t add value. For most flows, wrapping steps in test(...) is recommended — the label appears in your results and makes failures easier to locate.

`testContextDependencies`

testContextDependencies is exported for runner and tooling integration. Flow authors should usually use the public callback parameters above instead of depending on the raw runner dependency list.

`expect`

The exported expect is the assertion helper for web flows, backed by Playwright’s expect. All Playwright matchers are available — including auto-retrying locator matchers like toBeVisible, toHaveText, toHaveURL, and toHaveScreenshot. See Playwright’s locator assertions reference for the full list. Always import expect from @qawolf/flows/web rather than from @playwright/test directly, so that QA Wolf’s defaults (custom timeout, visual diffing) stay in effect. To assert on the meaning of AI-generated text rather than its exact wording, use ai.expect(locator).toSatisfy(...) from @qawolf/ai/web. See Assert on the meaning of generated text. Example:

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

export default flow(
  "Verify homepage",
  { target: "Web - Chrome", launch: true },
  async ({ page, test }) => {
    await test("hero heading is visible", async () => {
      await page.goto("https://example.com");
      await expect(page.getByRole("heading", { name: "Example Domain" })).toBeVisible();
    });
  },
);

For visual regression assertions with expect(page).toHaveScreenshot(...), see Web & Mobile web screenshots.

Flow conventions

@qawolf/flows

@qawolf/pom

@qawolf/testkit

@qawolf/emails

@qawolf/cli

Local execution

@qawolf/ci-sdk

Triggers

REST

Primary exports

Target model

Launch shapes

Defaults

Flow callback context

`testContextDependencies`

`expect`

​Primary exports

​Target model

​Launch shapes

​Defaults

​Flow callback context

​testContextDependencies

​expect

Primary exports

Target model

Launch shapes

Defaults

Flow callback context

`testContextDependencies`

`expect`