Testing

Fixtures

Fixtures give a test its device, its app and its screen, and options decide how they are set up. This page covers the built-in fixtures and options, app isolation, launch arguments, permissions, test.use, test.requires and fixtures of your own.

Built-in fixtures

A test-scoped fixture is set up for each test. A worker-scoped one is set up once per worker and shared by the tests that worker runs: a worker keeps one device for all its tests.

Starting the device and installing the app are not charged to a test's timeout. The device fixture has its own budget, the deviceTimeout option.

Options

Options are fixtures that hold a value. Set them in the config's use, in a project's use, or with test.use.

These choose the device. They are worker-scoped:

These shape each test. They are test-scoped:

Changing options for some tests

test.use sets options for a file, or for one describe:

test.describe('launch arguments and environment', () => {
  test.use({ launchArgs: ['--greeting', 'hello'], launchEnv: { STAGE: 'e2e' } })

  test('reach the app', async ({ screen }) => {
    await screen.getByTestId('nav-launch').tap()
    await expect(screen.getByTestId('launch-arguments')).toContainText('--greeting hello')
    await expect(screen.getByTestId('launch-environment')).toContainText('STAGE=e2e')
  })
})

A test-scoped option changes only how those tests start. A worker-scoped option such as locale or deviceType asks for a different device, so those tests run in a worker of their own.

App isolation

appIsolation decides what the app fixture does to your app before each test. The launch follows.

'clear' needs a platform that can clear app data, which Mac Catalyst cannot. 'reinstall' needs the app option, since that is the build it installs again.

The app fixture

app is the launched app. Its methods act on that app by its bundle id.

test('remembers the sign-in after a restart', async ({ app, screen }) => {
  await screen.getByLabel('Email').fill('ada@ex.co')
  await screen.getByRole('button', { name: 'Sign in' }).tap()
  await app.relaunch()
  await expect(screen.getByText('Signed in as ada@ex.co')).toBeVisible()
})

On Mac Catalyst there are no launch arguments, no environment, no deep links and no data clearing. On Android the arguments and environment reach the app as intent extras; see Android.

Permissions

permissions grants permissions before the app launches, so no prompt appears:

test.use({ permissions: ['location', 'photos'] })

Inside a test, app.setPermissions({ revoke: ['location'] }) changes them. To test the prompt itself, leave the permission out and answer the prompt through screen.system.

The device and runtime fixtures

device is the worker's session. It has the session's facts (sessionId, platform, resolved with the device type and OS that were chosen, installed, screenSize) and these methods:

For anything else the runtime can do, call the procedure by its id. The runtime fixture has one method, call(id, input), and device.runtime is the same thing bound to this device. Each call shows as a step in the report and the trace:

test('reads the device log', async ({ device }, testInfo) => {
  const { lines } = await device.runtime.call('logs.read', {
    sessionId: device.sessionId,
    limit: 100,
  })
  await testInfo.attach('device log', {
    body: JSON.stringify(lines, null, 2),
    contentType: 'application/json',
  })
})

The protocol reference lists every procedure with its input and output.

Requiring a capability

Platforms differ. test.requires skips a file's or a describe's tests on a platform that does not declare a capability, and records the reason:

test.describe('gestures', () => {
  test.requires('input.touch')

  test('a long press is recognised', async ({ screen }) => {
    await screen.getByTestId('nav-gestures').tap()
    await screen.getByTestId('gesture-area').longPress()
    await expect(screen.getByTestId('last-gesture')).toHaveText('Last gesture: long press')
  })
})

On Mac Catalyst that test is skipped with "requires input.touch, which catalyst does not declare". A second argument asks for a value: test.requires('input.keyboard', 'keys') for key presses, test.requires('input.buttons', 'back') for a button, test.requires('input.maxContacts', 2) for at least two fingers. Call it at the top of a file or a describe, not inside a test. The PlatformCapabilities type lists every capability.

A project whose own use needs something its platform lacks is refused before anything runs: launchArgs or permissions on Mac Catalyst, for example, or an .apk as the app of an iOS project.

Your own fixtures

test.extend adds fixtures and options. A fixture function sets up, hands its value to the test with use, and tears down after use returns.

// e2e/fixtures.ts
import { test as base, type Screen } from '@alivelabs/troupe'

interface TestUser {
  email: string
  password: string
}

export const test = base.extend<{ testUser: TestUser; signedIn: Screen }>({
  // An option: a default that a project's `use` or `test.use` can replace.
  testUser: [{ email: 'ada@ex.co', password: 'pw' }, { option: true }],

  signedIn: async ({ screen, testUser }, use) => {
    await screen.getByLabel('Email').fill(testUser.email)
    await screen.getByLabel('Password').fill(testUser.password)
    await screen.getByRole('button', { name: 'Sign in' }).tap()
    await use(screen)
  },
})

// e2e/orders.e2e.ts
import { expect } from '@alivelabs/troupe'
import { test } from './fixtures.ts'

test('lists past orders', async ({ signedIn }) => {
  await signedIn.getByRole('tab', { name: 'Orders' }).tap()
  await expect(signedIn.getByRole('listitem')).toHaveCount(2)
})

A fixture, like a test, must destructure its first parameter. Write a fixture as [value, options] to set:

mergeTests(testA, testB) combines the fixtures of several test objects. A fixture whose name starts with _ is internal: the report and the trace viewer hide its steps unless you ask for them.

Next

• Configuration
• Actions
• Traces
• The platform pages