Skip to main content

Breaking: @trackunit/iris-app-playwright v1.0.0 requires awaiting irisApp()

@trackunit/iris-app-playwright v1.0.0 is a breaking release: irisApp() now returns a Promise<FrameLocator> in every environment. Await it before using the app fixture:

// Before — no longer works
const app = irisApp();
await irisApp().getByTestId("asset-list").click();

// After
const app = await irisApp();
await app.getByTestId("asset-list").click();

// Or parenthesize a receiver chain
await (await irisApp()).getByTestId("asset-list").click();

Why this changed​

The stable promise contract allows tests that run against a feature branch to wait for the matching Iris App iframe before making page assertions. If that iframe never appears, the failure can be classified as host never became ready instead of surfacing as a misleading app assertion failure.

In normal external development, where NX_FEATURE_BRANCH_BASE_URL is not set, there is no additional wait: irisApp() resolves immediately while retaining the same promise-based API. The shared fixture also selects the first matching iframe, avoiding Playwright strict-mode failures when several matching iframes are present.

Migrate your tests​

The package includes the v1-0-0-await-iris-app migration. Update your Trackunit dependencies and run their migrations:

npx nx g @trackunit/migrations:migrate
npx nx g @trackunit/migrations:run-migrations

The migration:

  • awaits irisApp() calls inside async functions
  • changes local () => FrameLocator fixture types to () => Promise<FrameLocator>
  • leaves calls that are already awaited unchanged
  • reports synchronous locations as file:line so you can update them manually

For the complete update process, see Maintaining Your Application.