playwright-magic-steps

Auto-transform JavaScript comments into Playwright steps.

Example

Test code:

test('Check home page', async ({ page }) => {
  // step: Open home page
  await page.goto('https://playwright.dev');
  // step: Click "Get started" link
  await page.getByRole('link', { name: 'Get started' }).click();
  // step: Check page title
  await expect(page).toHaveTitle('Installation | Playwright');
});

Report:

Test code actually executed:

test('Check home page', async ({ page }) => {
  await test.step('Open home page', async () => {
    await page.goto('https://playwright.dev');
  });
  await test.step('Click "Get started" link', async () => {
    await page.getByRole('link', { name: 'Get started' }).click();
  });
  await test.step('Check page title', async () => {
    await expect(page).toHaveTitle('Installation | Playwright');
  });
});

Installation

Install from npm:

npm install -D playwright-magic-steps

Configuration

CommonJS projects

• Option 1 - add the following code to the Playwright config:

  import 'playwright-magic-steps'; // <- enables magic steps
  import { defineConfig } from '@playwright/test';
  
  export default defineConfig({
    ...
  });

• Option 2 - run Playwright with the following NODE_OPTIONS (install cross-env if needed):

  npx cross-env NODE_OPTIONS="-r playwright-magic-steps" playwright test

ESM projects

Run Playwright with the following NODE_OPTIONS (install cross-env if needed):

npx cross-env NODE_OPTIONS="--import playwright-magic-steps/esm" playwright test

Usage

You can define steps with special comments.

1. Step start is defined by the comment: // step: {title}
2. Step end is defined by one of the following rules:

   • start of another step on the same indent:

     test('my test', async () => {
       // step: Open home page
       await page.goto('/');
       // step: Click button
     });

   • explicit comment // stepend on the same indent:

     test('my test', async () => {
       // step: Open home page
       await page.goto('/');
       // stepend
     });

   • indent is lower than indent of step start:

     test('my test', async () => {
       // step: Open home page
       await page.goto('/');
     });

Steps can be nested:

test('my test', async () => {
  // step: Open home page
  await page.goto('/');
  if (noAuth) {
    // step: Perform auth
    await page.goto('/login');
  }
});

[!IMPORTANT] Code indentation is important! Consider using Prettier or other auto-formatting tools.

Motivation

According to Golden Rule of testing, I try to keep my Playwright tests flat and simple. Wrapping code into test.step() adds extra visual complexity and nesting. Creating steps by comments makes test code clean and readable.

Caveats

This library performs string replacements in your code and can potentially break it. In that case you can disable magic steps -> your code will work as all instructions are JavaScript comments. Feel free to report any problems in issues.

License

MIT