playwright-magic-steps

Auto-transform JavaScript comments into Playwright steps.

• Example
• Installation
• Activation
  • CommonJS
  • ESM
• Usage
  • Step start
  • Step end
  • Nested steps
  • Variables
• Motivation
• Caveats
• Changelog
  • 0.4.0
• License

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

Activation

To enable magic steps transformation, you'll need to run Playwright with a pre-required module. You can include this module using the NODE_OPTIONS environment variable. The exact value will depend on whether your project uses CommonJS or ESM.

CommonJS

Run Playwright with the following -r flag in NODE_OPTIONS:

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

import 'playwright-magic-steps'; // <- enables magic steps
import { defineConfig } from '@playwright/test';

export default defineConfig({
  ...
});

ESM

Run Playwright with the following --import flag in NODE_OPTIONS:

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

Usage

You can define steps with special comments.

Step start

Step start is defined by the comment:

// step: {title}

Step end

Step end is defined by the one of the following rules (indent matters):

• start of another step with the same indent:

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

• explicit comment // stepend with the same indent:

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

• line indent is lower than indent of step start:

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

Nested steps

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.

Variables

You can use variables in step text like in template literals:

const searchTerm = 'foo';
// step: Enter search term ${searchTerm}
await page.getByRole('search').fill(searchTerm);

Be careful with variables in comments, as it can be not obvious for other team members. Alternatively, you can always use regular test.step() for such cases:

const searchTerm = 'foo';
await test.step(`Enter search term ${searchTerm}`, async () => {
  await page.getByRole('search').fill(searchTerm);
});  

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 more readable.

Caveats

This library performs string replacements in your code and can potentially break it. This is a price we pay for convenience.

If something gets broken, you can always opt-out magic steps. Your tests will run, because all instructions are plain JavaScript comments. Feel free to report any problems in issues.

Example of broken code:

test('Check home page', async ({ page }) => {
  // step: Open home page
  await page.goto('https://playwright.dev');
  const link = page.getByRole('link', { name: 'Get started' });

  // step: Click link
  await link.click();
});

Error:

ReferenceError: link is not defined

There is an error, because in the transformed code link variable is wrapped into the scope of the first step and not accessible in the second step:

test('Check home page', async ({ page }) => {
  await test.step('Open home page', async () => {
    await page.goto('https://playwright.dev');
    const link = page.getByRole('link', { name: 'Get started' });
  });

  await test.step('Click link', async () => {
    await link.click();
  }); 
});

How to fix:

• Move link variable to the second step (that is more logical):

  test('Check home page', async ({ page }) => {
    // step: Open home page
    await page.goto('https://playwright.dev');
  
    // step: Click link
    const link = page.getByRole('link', { name: 'Get started' });
    await link.click();
  });

• Close first step earlier (if link variable is shared between several steps):

  test('Check home page', async ({ page }) => {
    // step: Open home page
    await page.goto('https://playwright.dev');
    // stepend
  
    const link = page.getByRole('link', { name: 'Get started' });
  
    // step: Click link
    await link.click();
  });  

Changelog

0.4.0

• allow blank lines inside steps (#3)
• dropped support of magic steps activation via playwright.config.js as it does not work in Playwright 1.47

License

MIT