api.md

Playwright Test Utils

The testing directory within Ionic's codebase contains utilities that can be used to more easily test Stencil projects with Playwright.

Table of Contents

• test function
• page fixture
• Generators
• Matchers

test Function

The default test function has been extended to provide two custom options.

Fixture	Type	Description
page	E2EPage	An extension of the base page test fixture within Playwright
skip	E2ESkip	Used to skip tests based on text direction, mode, or browser

Usage

page

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.goto('path/to/file', config);
    });
  });
});

skip.mode (DEPRECATED)

Deprecated: Use a generator instead.

import { test } from '@utils/test/playwright';

test('my custom test', ({ page, skip }) => {
  skip.mode('md', 'This test is iOS-specific.');

  await page.goto('path/to/file');
});

skip.rtl (DEPRECATED)

Deprecated: Use a generator instead.

import { test } from '@utils/test/playwright';

test('my custom test', ({ page, skip }) => {
  skip.rtl('This test does not have RTL-specific behaviors.');

  await page.goto('path/to/file');
});

skip.browser

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page, skip }) => {
      skip.browser('webkit', 'This test does not work in WebKit yet.');
  
      await page.goto('path/to/file', config);
    });
  });
});

skip.browser with callback

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page, skip }) => {
      skip.browser((browserName: string) => browserName !== 'webkit', 'This tests a WebKit-specific behavior.');
  
      await page.goto('path/to/file', config);
    });
  });
});

page fixture

The page fixture has been extended to provide additional methods:

Method	Description
goto	The page.goto method extended to support a config from a generator and to automatically wait for Stencil components to initialize.
setContent	The page.setContent method extended to support a config from a generator and to automatically wait for Stencil components to initialize.
locator	The page.locator method extended to support spyOnEvent.
setIonViewport	Resizes the browser window to fit the entire height of ion-content on screen. Only needed when taking fullsize screenshots with ion-content.
waitForChanges	Waits for Stencil to re-render before proceeeding. This is typically only needed when you update a property on a component.
spyOnEvent	Creates an event spy that can be used to wait for a CustomEvent to be emitted.

Usage

Using goto

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.goto('src/components/test/alert/test/basic', config);
    });
  });
});

Using setContent

setContent should be used when you only need to render a small amount of markup.

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.setContent(`
        <ion-button>My Button</ion-button>
        <style>
          ion-button {
            --background: green;
          }
        </style>
      `, config);
    });
  });
});

Using locator

Locators can be used even if the target element is not in the DOM yet.

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.goto('src/components/test/alert/test/basic', config);
      
      // Alert is not in the DOM yet
      const alert = page.locator('ion-alert');
      
      await page.click('#open-alert');
      
      // Alert is in the DOM
      await expect(alert).toBeVisible();
    });
  });
});

spyOnEvent with Locators

Locators have been updated with a spyOnEvent method which allows you to listen for an event on the element that the locator matches. Note that Playwright does not support changing the type of an existing fixture, so Locators that use spyOnEvent need to be manually cast as E2ELocator:

import type { E2ELocator } from '@utils/test/playwright';

...

const alert = page.locator('ion-alert') as E2ELocator;
const ionAlertDidPresent = await alert.spyOnEvent('ionAlertDidPresent');

Using setIonViewport

setIonViewport is only needed when a) you are using ion-content and b) you need to take a screenshot of the full page (including content that may overflow offscreen).

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, screenshot, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.goto('src/components/test/alert/test/basic', config);
      
      await page.setIonViewport();
      
      await expect(page).toHaveScreenshot(screenshot('alert'));  
    });
  });
});

Using waitForChanges

waitForChanges is only needed when you must wait for Stencil to re-render before proceeding. This is commonly used when manually updating properties on Stencil components.

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.goto('src/components/test/modal/test/basic', config);
      
      const modal = page.locator('ion-modal');
      
      await modal.evaluate((el: HTMLIonModalElement) => el.canDismiss = false);
      
      // Wait for Stencil to re-render with the canDismiss changes
      await page.waitForChanges();
    });
  });
});

Using spyOnEvent

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, screenshot, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.goto('src/components/test/modal/test/basic', config);
      
      // Create spy to listen for event
      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
      
      await page.click('#present-modal');
      
      // Wait for the next emission of `ionModalDidPresent`
      await ionModalDidPresent.next();
    });
  });
});

Generators

Ionic generates tests to test different modes (iOS or MD), layouts (LTR or RTL), and themes (default or dark).

Customizing the test configs

The configs function accepts an object containing all the configurations you want to test. It then returns an array of each individual configuration combination. This result is iterated over and one or more tests are generated in each iteration.

Usage

Example 1: Default config

import { configs, test } from '@utils/test/playwright';

/**
 * This will generate the following test configs
 * iOS, LTR
 * iOS, RTL
 * Material Design, LTR
 * Material Design, RTL
 */
configs().forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      ...
    });
  });
});

Example 2: Configuring the mode

import { configs, test } from '@utils/test/playwright';

/**
 * This will generate the following test configs
 * iOS, LTR
 * iOS, RTL
 */
configs({ mode: ['ios'] }).forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      ...
    });
  });
});

Example 3: Configuring the direction

import { configs, test } from '@utils/test/playwright';

/**
 * This will generate the following test configs
 * Material Design, RTL
 * iOS, RTL
 */
configs({ directions: ['rtl'] }).forEach(({ config, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      ...
    });
  });
});

Using the return value from each configuration

Each value in the array returns by configs contains the following information:

Name	Description
config	An object containing a single test configuration. This gets passed to page.goto or page.setContent.
screenshot	A helper function that generates a unique screenshot name based on the test configuration.
title	A helper function that generates a unique test title based on the test configuration. Playwright requires that each test has a unique title since it uses that to generate a test ID.

Usage

Example

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, title }) => {
  /**
   * Use the "title" function to generate 
   * a "my test block" title with the test 
   * config appended to make it unique.
   * Example: my test block ios/ltr
   * Using "title" on the describe block
   * avoids the need to use "title" on each
   * inner test block.
   */
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      
      /**
       * Pass a single config object to
       * load the page with the correct mode,
       * text direction, and theme.
       */
      await page.goto('/src/components/alert/test/basic', config);
      
      /**
       * Use the "screenshot" function to generate
       * a "alert" screenshot title with the test
       * config appended to make it unique. Playwright
       * will also append the browser and platform.
       * Example: alert-ios-ltr-chrome-linux.png
       */
      await expect(page).toHaveScreenshot(screenshot('alert'));  
    });
  });
});

Matchers

Playwright comes with a set of matchers to do test assertions. However, Ionic has additional custom assertions.

Assertion	Description
toHaveReceivedEvent	Ensures an event has received an event at least once.
toHaveReceviedEventDetail	Ensures an event has been received with a specified CustomEvent.detail payload.
toHaveReceivedEventTimes	Ensures an event has been received a certain number of times.

Usage

Using toHaveReceivedEvent

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, screenshot, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.setContent(`
        <ion-input label="Email"></ion-input>
      `, config);
      
      const ionChange = await page.spyOnEvent('ionChange');
      const input = page.locator('ion-input');
      
      await input.type('[email protected]');
  
      // In this case you can also use await ionChange.next();
      await expect(ionChange).toHaveReceivedEvent();
    });
  });
});

Using toHaveReceivedEventDetail

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, screenshot, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.setContent(`
        <ion-input label="Email"></ion-input>
      `, config);
      
      const ionChange = await page.spyOnEvent('ionChange');
      const input = page.locator('ion-input');
      
      await input.type('[email protected]');
  
      await ionChange.next();
      await expect(ionChange).toHaveReceivedEventDetail({ value: '[email protected]' });
    });
  });
});

Using toHaveReceivedEventTimes

import { configs, test } from '@utils/test/playwright';

configs().forEach(({ config, screenshot, title }) => {
  test.describe(title('my test block'), () => {
    test('my custom test', ({ page }) => {
      await page.setContent(`
        <ion-input label="Email"></ion-input>
      `, config);
      
      const ionChange = await page.spyOnEvent('ionChange');
      const input = page.locator('ion-input');
      
      await input.type('[email protected]');
  
      await ionChange.next();
      
      await input.type('[email protected]');
      
      await ionChange.next();
      
      await expect(ionChange).toHaveReceivedEventTimes(2);
    });
  });
});