playwright-magic-steps

Auto-transform JavaScript comments into Playwright steps.

• Example
  • With AI
• 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');
});

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');
  });
});

With AI

You can utilize AI to generate tests with appropriate comments and get nice reports. Example prompt for ChatGPT:

Write playwright test in typescript:
- open playwright homepage
- navigate to get started section
- check that page title contains Installation

Add comment to each step in the format // step: {comment}

Generated test:

Playwright report:

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

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

If you need the same level steps to be nested - use anonymous {} block:

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

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