Introducing Playwright-magic-steps: Simplify your Test Automation Workflow

Intro

Hey Folks👋

Recently I’ve released playwright-magic-steps - a tool to make your Playwright tests cleaner and easier to read. The main idea is to define steps by JavaScript comments and then automatically transform them into test.step() calls. That helps to maintain a straightforward and organized test code while providing detailed step reports.

How It Works

Here’s a quick example to illustrate the transformation:

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

Transformed Test Code

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

The transformation is performed behind the scene, so you deal only with comments.

Do you notice how traditional test.step() functions clutter your code with visual complexity and nesting?

How to Setup

Magic steps setup depends on your project module system.

CommonJS Projects

Add the following code to your Playwright config:

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

export default defineConfig({
  // your config
});

Then run as usual:

npx playwright test

ESM Projects

Run Playwright with the following NODE_OPTIONS containing custom loader:

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

Report

After test execution Playwright report contains all defined steps:

Report example

Under the Hood

Playwright-magic-steps operates by intercepting the code of test files and replacing comments with test.step() calls. The interception process differs for CommonJS and ESM projects:

CommonJS Projects: Playwright uses pirates package to hook into require calls when loading test files. Playwright-magic-steps overwrites methods of pirates to intercept test code and convert comments into steps.
ESM Projects: For loading ESM tests, Playwright uses a separate loader thread utilizing Node.js customization hooks. Playwright-magic-steps wraps that loader and gets access to test code.

Important Considerations

Indentation Matters: Proper code indentation is crucial for the correct steps transformation. Using auto-formatting tools like Prettier is recommended.
Potential Caveats: Since the library performs string replacements in your code, it might introduce issues in some cases. If that happens, you can disable magic steps, and your code will still work as usual since the instructions are only JavaScript comments.

Conclusion

Following the Golden Rule of testing, we should keep test code as simple as possible, to save brain capacity for production code. I hope magic steps will help to achieve that. The project is new and still experimental, so give it a try and share your feedback ❤️