playwright-magic-steps


Auto-transform JavaScript comments into Playwright steps.

- Example
- With AI
- Installation
- Activation
- Activation for v0.x (deprecated)
- Usage
- Step start
- Step end
- Nested steps
- Variables
- Motivation
- Caveats
- Changelog
- 1.0.0
- 0.4.0
- License

Example

Test code:
``ts
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:

!image

Test code actually executed:
`ts
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');
});
});
`

$3


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 activate magic steps in your project, you should run Playwright with pre-required module, provided via -r flag in NODE_OPTIONS:

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

To enable magic steps in Playwright VS Code extension, add the following lines to .vscode/settings.json:
`json
"playwright.env": {
"NODE_OPTIONS": "-r playwright-magic-steps"
},
`

Activation for v0.x (deprecated)

Click to expand

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
`
To enable magic steps in Playwright VS Code extension, add the following lines to .vscode/settings.json:
`json
"playwright.env": {
"NODE_OPTIONS": "-r playwright-magic-steps"
},
`

#### ESM
Run Playwright with the following --import flag in NODE_OPTIONS:
`
npx cross-env NODE_OPTIONS="--import playwright-magic-steps/esm" playwright test
`
To enable magic steps in Playwright VS Code extension, add the following lines to .vscode/settings.json:
`json
"playwright.env": {
"NODE_OPTIONS": "--import playwright-magic-steps/esm"
},
`


Usage

You can define steps with special comments.

$3

Step start is defined by the comment:
`js
// step: {title}
`

$3

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

* start of another step with the same indent:
`ts
test('my test', async () => {
// step: Open home page
await page.goto('/');
// step: Click button
});
`

* explicit comment // stepend with the same indent:
`ts
test('my test', async () => {
// step: Open home page
await page.goto('/');
// stepend
});
`

* line indent is lower than indent of step start:
`ts
test('my test', async () => {
// step: Open home page
await page.goto('/');
});
`

$3


Steps can be nested:
`ts
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:
`ts
test('my test', async () => {
// step: login
{
// step: Open home page
await page.goto('/');
// step: Perform auth
await page.goto('/login');
}
});
`

$3

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

`js
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:
`js
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:
`ts
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:
`ts
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):
`ts
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):
`ts
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

$3

* Update dependencies.

$3

* [breaking] a new way to inject transformer code into Playwright, same approach for both cjs and esm. How to migrate:
- if you use magic steps in CJS project, no changes
- if you use magic steps in ESM project, replace the following:
`diff
-npx cross-env NODE_OPTIONS="--import playwright-magic-steps/esm" playwright test
+npx cross-env NODE_OPTIONS="-r playwright-magic-steps" playwright test
`

$3

* 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