externaluseBase

Callable

useBase<TestArgs, WorkerArgs>(baseTest: TestType<TestArgs, WorkerArgs>): TestApi<Omit<SerenityOptions, actors> & SerenityFixtures & TestArgs, WorkerArgs>

Creates a Serenity/JS BDD-style test API around the given Playwright base test.

Using default configuration

When your test scenario doesn't require custom test fixtures, and you're happy with the default base test offered by Playwright, you can import test API functions such as describe and it directly from @serenity-js/playwright-test.

import { describe, it, test } from '@serenity-js/playwright-test'
import { Log } from '@serenity-js/core'

// override default fixtures if needed
test.use({
  defaultActorName: 'Alice'
})

describe('Serenity/JS default test API', () => {

  it('enables easy access to actors and standard Playwright fixtures', async ({ actor, browserName }) => {
    await actor.attemptsTo(
      Log.the(browserName),
    )
  })
})

In the above example, importing test API functions directly from @serenity-js/playwright-test is the equivalent of the following setup:

import { test as playwrightBaseTest } from '@playwright/test'
import { useBase } from '@serenity-js/playwright-test'

const { describe, it, test, beforeEach, afterEach } = useBase(playwrightBaseTest)

Using custom fixtures

When your test scenario requires custom test fixtures, but you're still happy with the default base test offered by Playwright, you can create fixture-aware test API functions such as describe and it by calling useFixtures.

For example, you can create a test scenario using a static message fixture as follows:

import { useFixtures } from '@serenity-js/playwright-test'
import { Log } from '@serenity-js/core'

const { describe, it } = useFixtures<{ message: string }>({
  message: 'Hello world!'
})

describe('Serenity/JS useFixtures', () => {

  it('enables injecting custom test fixtures into test scenarios', async ({ actor, message }) => {
    await actor.attemptsTo(
      Log.the(message),
    )
  })
})

The value of your test fixtures can be either static or dynamic and based on the value of other fixtures.

To create a dynamic test fixture use the function syntax:

import { Log } from '@serenity-js/core'
import { useFixtures } from '@serenity-js/playwright-test'

const { describe, it } = useFixtures<{ message: string }>({
  message: async ({ actor }, use) => {
    await use(`Hello, ${ actor.name }`);
  }
})

describe('Serenity/JS useFixtures', () => {

  it('enables injecting custom test fixtures into test scenarios', async ({ actor, message }) => {
    await actor.attemptsTo(
      Log.the(message),
    )
  })
})

In the above example, creating test API functions via useFixtures is the equivalent of the following setup:

import { test as playwrightBaseTest } from '@playwright/test'
import { useBase } from '@serenity-js/playwright-test'

const { describe, it, test, beforeEach, afterEach } = useBase(playwrightBaseTest)
  .useFixtures<{ message: string }>({
    message: async ({ actor }, use) => {
      await use(`Hello, ${ actor.name }`);
    }
  })

Using custom base test

In cases where you need to use a non-default base test, for example when doing UI component testing, you can create Serenity/JS test API functions around your preferred base test.

import { test as componentTest } from '@playwright/experimental-ct-react'
import { Ensure, contain } from '@serenity-js/assertions'
import { useBase } from '@serenity-js/playwright-test'
import { Enter, PageElement, CssClasses } from '@serenity-js/web'

import EmailInput from './EmailInput';

const { it, describe } = useBase(componentTest).useFixtures<{ emailAddress: string }>({
  emailAddress: ({ actor }, use) => {
    use(`${ actor.name }@example.org`)
  }
})

describe('EmailInput', () => {

  it('allows valid email addresses', async ({ actor, mount, emailAddress }) => {
    const nativeComponent = await mount(<EmailInput/>);

    const component = PageElement.from(nativeComponent);

    await actor.attemptsTo(
      Enter.theValue(emailAddress).into(component),
      Ensure.that(CssClasses.of(component), contain('valid')),
    )
  })
})

Type parameters

TestArgs: Record<string, any>
WorkerArgs: Record<string, any> = object

Parameters

externalbaseTest: TestType<TestArgs, WorkerArgs>