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:
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 ❤️
Top comments (0)