externaldescribe

Callable

• describe(title: string, callback: () => void): void
• describe(callback: () => void): void
• describe(title: string, details: TestDetails, callback: () => void): void

---

• Declares a group of test scenarios.

  Example

  import { Ensure, equals } from '@serenity-js/assertions'
  import { describe, it, test } from '@serenity-js/playwright-test'
  import { Photographer, TakePhotosOfFailures, Value } from '@serenity-js/web'
  
  describe(`Todo List App`, () => {
  
    test.use({
      defaultActorName: 'Serena',
      crew: [
        Photographer.whoWill(TakePhotosOfFailures),
      ],
    })
  
    it(`should allow me to add a todo item`, async ({ actor }) => {
      await actor.attemptsTo(
        startWithAnEmptyList(),
  
        recordItem('Buy some milk'),
  
        Ensure.that(itemNames(), equals([
          'Buy some milk',
        ])),
      )
    })
  
    it('should clear text input field when an item is added', async ({ actor }) => {
      await actor.attemptsTo(
        startWithAnEmptyList(),
  
        recordItem('Buy some milk'),
  
        Ensure.that(Value.of(newTodoInput()), equals('')),
      )
    })
  })

  Learn more

  • Declaring a Serenity/JS test scenario
  • Playwright Test describe function
  • Serenity/JS + Playwright Test project template

  ---

  Parameters

  • externaltitle: string

  • externalcallback: () => void

  Returns void

Index

Properties

• only
• skip
• fixme
• serial
• parallel
• configure

Properties

externalonly

only: SuiteFunction

Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing else.

Usage

test.describe.only('focused group', () => {
  test('in the focused group', async ({ page }) => {
    // This test will run
  });
});
test('not in the focused group', async ({ page }) => {
  // This test will not run
});

@param

Group title.

@param

A callback that is run immediately when calling test.describe.only(title, callback). Any tests added in this callback will belong to the group.

externalskip

skip: SuiteFunction

Declares a skipped test group, similarly to test.describe(title, callback). Tests in the skipped group are never run.

Usage

test.describe.skip('skipped group', () => {
  test('example', async ({ page }) => {
    // This test will not run
  });
});

@param

Group title.

@param

A callback that is run immediately when calling test.describe.skip(title, callback). Any tests added in this callback will belong to the group, and will not be run.

externalfixme

fixme: SuiteFunction

Declares a test group similarly to test.describe(title, callback). Tests in this group are marked as "fixme" and will not be executed.

Usage

test.describe.fixme('broken tests', () => {
  test('example', async ({ page }) => {
    // This test will not run
  });
});

@param

Group title.

@param

A callback that is run immediately when calling test.describe.fixme(title, callback). Any tests added in this callback will belong to the group, and will not be run.

externalserial

serial: SuiteFunction & { only: SuiteFunction }

NOTE See test.describe.configure([options]) for the preferred way of configuring the execution mode.

Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together.

NOTE Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

Usage

test.describe.serial('group', () => {
  test('runs first', async ({ page }) => {});
  test('runs second', async ({ page }) => {});
});

@param

Group title.

@param

A callback that is run immediately when calling test.describe.serial(title, callback). Any tests added in this callback will belong to the group.

externalparallel

parallel: SuiteFunction & { only: SuiteFunction }

NOTE See test.describe.configure([options]) for the preferred way of configuring the execution mode.

Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after another, but using test.describe.parallel(title, callback) allows them to run in parallel.

Usage

test.describe.parallel('group', () => {
  test('runs in parallel 1', async ({ page }) => {});
  test('runs in parallel 2', async ({ page }) => {});
});

Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of the parallel tests executes all relevant hooks.

@param

Group title.

@param

A callback that is run immediately when calling test.describe.parallel(title, callback). Any tests added in this callback will belong to the group.

externalconfigure

configure: (options: { mode?: default | parallel | serial; retries?: number; timeout?: number }) => void

Configures the enclosing scope. Can be executed either on the top level or inside a describe. Configuration applies to the entire scope, regardless of whether it run before or after the test declaration.

Learn more about the execution modes here.

Usage

• Running tests in parallel.

  // Run all the tests in the file concurrently using parallel workers.
  test.describe.configure({ mode: 'parallel' });
  test('runs in parallel 1', async ({ page }) => {});
  test('runs in parallel 2', async ({ page }) => {});
• Running tests serially, retrying from the start. NOTE Running serially is not recommended. It is usually better to make your tests isolated, so they can be run independently.

  // Annotate tests as inter-dependent.
  test.describe.configure({ mode: 'serial' });
  test('runs first', async ({ page }) => {});
  test('runs second', async ({ page }) => {});
• Configuring retries and timeout for each test.

  // Each test in the file will be retried twice and have a timeout of 20 seconds.
  test.describe.configure({ retries: 2, timeout: 20_000 });
  test('runs first', async ({ page }) => {});
  test('runs second', async ({ page }) => {});
• Run multiple describes in parallel, but tests inside each describe in order.

  test.describe.configure({ mode: 'parallel' });
  
  test.describe('A, runs in parallel with B', () => {
    test.describe.configure({ mode: 'default' });
    test('in order A1', async ({ page }) => {});
    test('in order A2', async ({ page }) => {});
  });
  
  test.describe('B, runs in parallel with A', () => {
    test.describe.configure({ mode: 'default' });
    test('in order B1', async ({ page }) => {});
    test('in order B2', async ({ page }) => {});
  });

---

Type declaration

• • (options: { mode?: default | parallel | serial; retries?: number; timeout?: number }): void

  • Parameters

    • externaloptions: { mode?: default | parallel | serial; retries?: number; timeout?: number }

    • externaloptionalmode: default | parallel | serial

    • externaloptionalretries: number

    • externaloptionaltimeout: number

    Returns void