DEV Community: Vitaliy Potapov

Turbopack: A Better Way to Inline SVG in Next.js 16

Vitaliy Potapov — Wed, 19 Nov 2025 18:50:28 +0000

Next.js 16 enabled Turbopack as a default bundler. It is fast, modern, and noticeably improves the DX in many areas.

But when I started adding SVG icons to my project, I realized the common options did not cover my needs:

I wanted icons to be inlined, so they display instantly without an extra network request.
I wanted to avoid the SVG-in-JS performance penalty (more on this later).
I wanted to customize icon color via CSS.
And everything had to be compatible with Turbopack, not just Webpack.

I tried the popular SVG approaches for Next.js apps: built-in <Image />, SVGR, SVG sprites. They are all well-known and widely used, but none of them fully matched my requirements. Let’s look at why they fall short and how I built a custom Turbopack loader that solved the issue.

Why Existing Approaches Fall Short

Let me quickly show why the most common ways to handle SVGs in Next.js fall short for SVG icons.

1. Next `<Image />`

Next.js has excellent built-in support for importing SVGs as static images. The usage is straightforward:

import Image from 'next/image';
import myIcon from './icon.svg';

export default function Page() {
  return <Image src={myIcon} alt="my icon" />;
}

The imported myIcon object looks like this:

{
  src: "/_next/static/media/icon.682156e7.svg",
  width: 24,
  height: 24,
}

In HTML it appears as <img> tag:

This has two big benefits:

✅ Turbopack automatically copies the original SVG to the output directory with a hashed filename, so the file is immutable and cacheable.
✅ It also extracts the intrinsic width and height, ensuring proper layout without shifts.

But for icons specifically, this approach has two major drawbacks:

❌ It generates a separate HTTP request for every icon, which means your icons may not appear instantly.
❌ You can’t change the icon color via CSS, since the SVG isn’t inlined.

Great for logos and large illustrations. Not great for small UI icons.

2. SVGR (`@svgr/webpack`)

SVGR converts an SVG into a React component. Turbopack supports this loader, and it is a pretty popular pattern:

import Icon from './icon.svg';

export default function Page() {
  return <Icon className="text-red-500" />;
}

In HTML it inlines SVG content directly into the DOM:

Pros & cons:

✅ You can fully customize the icon via CSS.
✅ Since the SVG is inlined, it renders instantly.
❌ This approach moves the entire SVG markup into your JavaScript bundle. For small icons this may look harmless, but it adds up quickly, especially in apps with dozens or hundreds of icons.

There’s a great deep-dive on this topic: Breaking Up with SVG-in-JS.

In short: extra DOM nodes, extra JS, extra parsing, and none of it is necessary if your SVG is just a static asset.

Due to this performance cost, I stopped using SVGR in my projects.

3. SVG Sprite Maps

Sprite maps combine multiple SVGs into a single <svg> file, and individual icons are referenced with the <use> tag.

Example SVG sprite:

<svg>
  <symbol id="icon1">
    <path d="..." />
  </symbol>
  ...
</svg>

Usage in JSX:

return <svg><use href="/sprite.svg#icon1" /></svg>;

If you want a detailed explanation of the sprite technique, here is a great article: Use svg sprite icons in React.

In the context of Turbopack, the real question is how to generate the sprite effectively. There are two ways:

a) Pre-build script

A script crawls your icon directory and generates one giant sprite.

Pros & cons:

✅ Works with any framework or bundler
❌ Includes every icon, not just the ones you import
❌ Requires an extra script + watcher integration → not ideal DX

b) Loader-based sprite generation

A loader collects only the SVGs you actually import and builds a sprite automatically.

Pros & cons:

✅ Only includes used icons
❌ Not compatible with Turbopack: currently Turbopack loaders can produce only JavaScript output and do not support this.emitFile() method (unlike webpack).

Extra issue: Safari doesn’t render sprite icons that contain SVG filters (bug report). I tested this and confirmed the issue on Safari 26.1. Many of my icons rely on filters, so this made sprite maps unusable for me.

Solution: Inline Small SVGs as Data URI

Finally, I ended up looking at another option: what if small SVG icons were just inlined directly as data URIs?

Ideally, the imported SVG would provide the same object as an external image, but with a data URI in src:

import myIcon from './icon.svg';

/*
{
  src: "data:image/svg+xml,...",
  width: 32,
  height: 32
}
*/

For icons, this has a few natural advantages:

The icon appears instantly.
The SVG stays as a static asset: no extra DOM nodes, no SVG-in-JS overhead.
The image's width and height preserve the intrinsic size.
Since it behaves like a normal image import, it can be passed to the <Image /> component:

import Image from 'next/image';
import myIcon from './icon.svg';

export default function Page() {
  return <Image src={myIcon} alt="my icon" />;
}

But none of the existing loaders supported this pattern, so I decided to build my own.

Building a Custom Turbopack SVG Loader

The loader should perform three things:

convert SVG content into a compact data URI
extract SVG’s intrinsic width and height for correct default sizing
return these values as an object { src, width, height }

The good news is that all of this can be done with a few existing packages:

svgo to optimize the SVG markup
mini-svg-data-uri to convert it into a very compact data URL
image-size to extract intrinsic dimensions (the same library Next.js uses internally)

Because of that, the loader code turned out to be surprisingly small:

// inline-svg-loader.js
const { optimize } = require("svgo");
const svgToMiniDataURI = require("mini-svg-data-uri");
const { imageSize } = require("image-size");

module.exports = function (content) {
  this.cacheable?.();

  const optimized = optimize(content);
  const src = svgToMiniDataURI(optimized.data);
  const { width, height } = imageSize(Buffer.from(content));
  const result = { src, width, height };

  return `export default ${JSON.stringify(result)};`;
};

It uses CommonJS syntax, because Turbopack does not support ESM loaders yet.

Then, I added the loader to my next.config.js so Turbopack applies it to .svg imports:

const nextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['./inline-svg-loader.js'],
        as: '*.js',
      },
    },
  },
};

export default nextConfig;

Given this setup, my Next.js project correctly displayed checkmark SVG icon inlined into the <img> tag:

Full data URI is collapsed by the devtools.

However, there are two problems that still need to be resolved:

Now every SVG is inlined, including large images.
How to change the color of the inlined SVG?

Problem 1: Conditional Inlining

Ideally, I wanted a setup where:

small SVGs are inlined as data URIs
large SVGs fall back to the built-in Next.js behavior
both produce the same {src, width, height} object compatible with <Image /> component

Fortunately, Next.js 16 shipped exactly what I need: Turbopack condition rules. These rules allow loaders to conditionally apply only to files matching different criteria.

The key part is the content condition, which checks the entire file body. Since it accepts a RegExp, it’s possible to match files by approximate size. For example, this pattern matches files up to around 4 Kb:

/^[\s\S]{0,4000}$/

It uses [\s\S] to match any character including newlines.

Using this, I updated the Turbopack configuration to only apply the inline loader to small SVGs:

const nextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['./inline-svg-loader.js'],
        condition: {
          content: /^[\s\S]{0,4000}$/, // Inline SVGs smaller than ~4Kb
        },
        as: '*.js',
      },
    },
  },
};

export default nextConfig;

To illustrate conditional inlining, I created a page with two SVG images:

a checkmark icon (436 bytes)
new W3C logo (42 Kb)

Next.js correctly renders both images: the first one is inlined and the second is external:

A nice use-case for Turbopack's built-in capabilities!

Hopefully, Turbopack will add a dedicated condition for filesize in the future. I've opened a feature request for that in the Next.js repo.

Problem 2: Customizing Icon Color

The approach to coloring an SVG depends on how much customization you need. If you want to style different parts of the SVG independently, it must be rendered as DOM nodes anyway. But most of my icons are monochrome, and the only requirement is setting a single color via CSS. For this case, there is a clean workaround: CSS masking.

Instead of modifying the SVG itself, the color is set to the element’s background and the SVG defines the visible shape:

The result is a fully color-customizable icon that still behaves like a regular image asset.

The masking setup:

render the <img> tag with src set to an empty image
set width and height attributes to the intrinsic values for SVG
set the CSS mask property to the actual icon data URI
set background-color: currentcolor to make the icon color customizable

I wrapped it into the universal Icon.tsx component:

/**
 * A component for rendering mono-color SVG icons using the current text color.
 */
import { type ComponentProps } from 'react';
import { type StaticImageData } from 'next/image';

type IconProps = Omit<ComponentProps<'img'>, 'src'> & {
  src: StaticImageData;
};

const EMPTY_SVG = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'/%3E`;

export default function Icon({ src, width, height, style, ...props }: IconProps) {
  return (
    <img
      width={width ?? src.width}
      height={height ?? src.height}
      src={EMPTY_SVG}
      style={{
        ...style,
        backgroundColor: 'currentcolor',
        mask: `url("${src.src}") no-repeat center / contain`,
      }}
      {...props}
    />
  );
}

With this setup, customizing the icon color becomes as simple as writing normal CSS:

import Icon from './Icon';
import myIcon from './icon.svg';

// Set color with style
return <Icon src={myIcon} style={{ color: 'red' }} />;

// Set color with Tailwind
return <Icon src={myIcon} className="text-green-600" />;

// Set both size and color
return <Icon src={myIcon} width={64} height={64} className="text-blue-600" />;

Output:

This method works well for any single-color SVG icon. Multi-color icons could still be rendered normally with <Image /> component.

Packaging the Loader

Although the inline loader is only a few lines of code, I quickly found myself wanting to reuse it in multiple projects. Instead of copying the file around, I built a small npm package that includes all required dependencies and works directly with Turbopack’s configuration rules.

The package lives here: turbopack-inline-svg-loader

You can install it and pass the loader name to the Turbopack configuration:

const nextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['turbopack-inline-svg-loader'],
        condition: {
          content: /^[\s\S]{0,4000}$/, // Inline SVGs smaller than ~4Kb
        },
        as: '*.js',
      },
    },
  },
};

export default nextConfig;

This keeps the project setup clean and allows the loader to be shared and updated like any other dependency.

Conclusion

The combination of a custom loader, Turbopack’s condition rules and CSS masking provided a flexible SVG workflow in my Next.js projects:

small icons are inlined and render instantly.
larger SVGs fallback to the default Next.js loader and remain external.
both imports work seamlessly with the <Image /> component.
monochrome icons can be styled via CSS.

For use cases requiring deeper control of SVG internals, SVGR or inlined markup is still the right choice. But for many other projects, I believe this approach should be a practical and efficient alternative. Feel free to share your feedback!

Authentication in Playwright: You Might Not Need Project Dependencies

Vitaliy Potapov — Fri, 24 Oct 2025 09:21:08 +0000

If your Playwright suite mixes public pages and authenticated areas, or you test multiple roles like user and admin, the standard “setup project” approach for auth can make your runs slower than they need to be.

Here’s a simpler pattern that authenticates on demand, plays nicely with sharding, and keeps your config to one project per browser.

The usual way: a “setup” project

The Playwright docs on authentication recommend authenticating in a dedicated setup project and declaring it as a dependency for your browser projects. The dependency project runs first and prepares storageState that other projects reuse.

That’s convenient and visible in reports, but there’s a cost.

The big drawback: setup runs even when not needed

From the docs:

The setup project will always run and authenticate before all the tests

In practice this means:

You have public and authenticated tests. Even if you run only public tests, the setup still authenticates.
You have multiple roles. The docs show multiple signed in roles where the setup logs in both admin and user. If you run only admin tests, the user login still happens because the setup runs in full.
It gets worse with sharding. Imagine 2 shards:
- Shard 1 executes user.spec.ts
- Shard 2 executes admin.spec.ts
With project dependencies, both shards still execute the full setup up front, repeating both logins unnecessarily.

You can split the config into separate projects per role, each with its own setup. That works, but once you add different browsers, the matrix grows and your config becomes hard to reason about. I prefer one project per browser and nothing else.

A simpler idea

What I really wanted:

The first test that actually needs auth does the sign-in while others wait.
Once done, the same storage state is shared across workers/tests that need it.
Optionally, persist the state for a while on disk so local runs become instant.

That’s exactly what I use today with @global-cache/playwright, which I built after running into these downsides. Here’s how.

Code: multi-role auth on demand (no setup project)

I’ll use the example from the docs with admin and user roles. But instead of putting both logins into a setup project, I create a helper function and wrap authentication steps in globalCache.get():

// tests/helpers/auth.ts
import type { Browser } from '@playwright/test';
import { expect } from '@playwright/test';
import { globalCache } from '@global-cache/playwright';

/**
 * Performs sign-in for a given role and caches the auth state for the whole run.
 */
export async function signIn(browser: Browser, role: 'admin' | 'user') {
  return globalCache.get(`auth-state-${role}`, async () => {
    console.log(`Signing-in as: ${role}`);
    const page = await browser.newPage();

    // Perform authentication steps. Replace these actions with your own.
    await page.goto('https://github.com/login');
    await page.getByLabel('Username or email address').fill(role);
    await page.getByLabel('Password').fill('password');
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Wait until the page reaches a state where all cookies are set.
    await expect(page.getByRole('button', { name: 'View profile and more' })).toBeVisible();

    // Return authenticated state (cookies + localStorage)
    return page.context().storageState();
  });
}

Now each spec calls this helper inside a storageState fixture to authenticate only the role it needs, and only if a test actually runs:

`tests/admin.spec.ts`

import { test } from '@playwright/test';
import { signIn } from './helpers/auth';

// Make all tests in this file run as "admin"
test.use({
  storageState: async ({ browser }, use) => {
    const state = await signIn(browser, 'admin');
    await use(state);
  },
});

test('admin: sees dashboard', async ({ page }) => {
  await page.goto('/admin');
  // ...
});

`tests/user.spec.ts`

import { test } from '@playwright/test';
import { signIn } from './helpers/auth';

// Make all tests in this file run as "user"
test.use({
  storageState: async ({ browser }, use) => {
    const state = await signIn(browser, 'user');
    await use(state);
  },
});

test('user: can view profile', async ({ page }) => {
  await page.goto('/me');
  // ...
});

Running the tests

Below are 4 common runs to check the authentication setup:

1) Run everything (user + admin)

$ npx playwright test

Running 2 tests using 2 workers

  ✓  1 test/admin.spec.ts:11:5 › admin: sees dashboard (2.7s)
  ✓  2 test/user.spec.ts:11:5 › user: can view profile (2.8s)
Signing in as: admin
Signing in as: user

  2 passed (3.5s)

What happens: user and admin authenticate once each, then all tests reuse their storage states.

2) Run only "user" tests

$ npx playwright test tests/user.spec.ts

Running 1 test using 1 worker

  ✓  1 test/user.spec.ts:11:5 › user: can view profile (2.8s)
Signing in as: user

What happens: only the user role authenticates; admin never runs.

3) Run only "admin" tests

$ npx playwright test tests/admin.spec.ts

Running 1 test using 1 worker

  ✓  1 test/admin.spec.ts:11:5 › admin: sees dashboard (2.7s)
Signing in as: admin

What happens: only the admin role authenticates; user never runs.

4) Run on two shards (split by files)

Shard 1:

$ npx playwright test --shard=1/2

Running 1 test using 1 worker, shard 1 of 2

  ✓  1 test/admin.spec.ts:11:5 › admin: sees dashboard (2.7s)
Signing in as: admin

  1 passed (3.7s)

Shard 2:

$ npx playwright test --shard=2/2

Running 1 test using 1 worker, shard 2 of 2

  ✓  1 test/user.spec.ts:11:5 › user: can view profile (2.7s)
Signing in as: user

  1 passed (3.6s)

What happens: the first shard authenticates admin; the second shard authenticates user. Each shard pays only for its role, which is why this setup executes faster than a multi-role dependency project.

In all examples, authentication runs only for roles that your tests actually touch. In practice this cuts setup time and makes your tests run faster.

Bonus: persistent auth for local dev

For local development, you can keep login state on disk for a limited time. For example, to cache for 1 hour, add a { ttl: '1 hour' } parameter to the authentication call:

await globalCache.get(`auth-state-${role}`, { ttl: '1 hour' }, async () => {
  // ...perform login and return storageState()
});

The cache files live under .global-cache by default. You can inspect them and delete them to force a cache update.

How to enable Global Cache

To enable Global Cache, wrap your Playwright config with globalCache.wrap():

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { globalCache } from '@global-cache/playwright';

const config = defineConfig({
  projects: [
    { name: 'chromium' }, // keep it simple: one project per browser
  ],
  // ...any other options
});

export default globalCache.wrap(config);

Notes

If tests modify server-side state and you need isolation per worker, scope the cache key by worker:

  const key = `auth-state-${role}-${testInfo.workerIndex}`;

Make cache keys role-aware and environment-aware. Include tenant/locale and base URL if you test multiple envs:

  const key = `auth-${role}-${locale}-${envName}`;

Prefer API-based login for speed and stability. See the example: auth via API with global cache.

Side-by-side: dependency project vs Global Cache

Aspect	Dependency project	Global Cache
When auth runs	Always before tests	Only when a test needs it
Multiple roles	All roles log in up front	Only selected roles log in
Sharding	Each shard pays full setup	Each shard computes only its role
Config	Projects × roles × browsers	One project per browser
Persist across runs	Roll your own	TTL for local runs

Wrap-up

Project dependencies are solid and officially recommended. But when you mix public pages, multiple roles, or heavy sharding, paying the authentication cost every time adds up. By authenticating on demand and sharing that state, you keep config lean, you only log in when a test truly needs it, and your local loop becomes fast with a short TTL.

If that sounds familiar, give this pattern a try and share your feedback ❤️

Global Cache: Make Playwright BeforeAll Run Once for All Workers

Vitaliy Potapov — Tue, 12 Aug 2025 08:30:04 +0000

Intro

Let’s start with a quick quiz:
How many times will the BeforeAll hook run in the following Playwright code?

import { test, expect } from '@playwright/test';

test.beforeAll(() => {
  console.log('Executing beforeAll...');
});

test('test 1', () => {
  expect(true).toEqual(true);
});

test('test 2', () => {
  expect(true).toEqual(false);
});

test('test 3', () => {
  expect(true).toEqual(false);
});

Check the answer!

At first glance, it seems like it should run once before all tests as the name suggests.
But actually, it will be called 2, 3 or even 4+ times, depending on your Playwright configuration.

In case of 1 worker, the hook will be called 2 times, because when test 2 fails, Playwright will create a new worker and re-run BeforeAll hook for test 3:

npx playwright test --workers=1

In case of 3 workers and fullyParallel mode, the hook will be called 3 times, because each test runs in its own worker:

npx playwright test --workers=3 --fully-parallel

There is no way to ensure this BeforeAll hook executes only once across the entire test run, as many people expect. Despite its name, BeforeAll is called once per worker, not once per test run.

Can you make it execute 4+ times?

The "Test Setup" Parallelization Problem

Setting up data before the actual tests is a very common task. You may need to authenticate a user, seed a database, or prepare an environment. Things get trickier when tests run in parallel, because some setup code should run only once, even if there are multiple workers.

Playwright provides several approaches, each with its own advantages and drawbacks. Let’s go through them first, and then I'll share a solution that takes the best parts of each.

Example

Imagine a site that has public and authenticated pages. You are asked to write E2E tests for it, and you create two spec files:

// auth.spec.ts

test('test authenticated page', () => { ... });

// no-auth.spec.ts

test('test non-authenticated page', () => { ... });

There are 3 options to set up authentication:

Project dependency
Global setup
BeforeAll hook

1. Project dependency

Playwright docs recommend using a separate setup project for authentication. Instead of tests, this project contains authentication code and is set as a dependency for the main project:

// playwright.config.ts

export default defineConfig({
  projects: [
    // Setup project
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: {
        // Use prepared auth state.
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ]

✅ Advantages of the approach:

Authentication runs only once
Authentication steps are visible in the report

❌ Downsides:

Requires an extra project
Authentication always runs, even for tests that do not need it

To illustrate the last point, I'll add a reset auth code to no-auth.spec.ts as recommended in the docs:

// no-auth.spec.ts

// Reset storage state for this file to avoid being authenticated
test.use({ storageState: { cookies: [], origins: [] } });

test('test non-authenticated page', () => { ... });

And run only this file:

npx playwright test no-auth.spec.ts

You can see that the setup project runs the authentication flow, which is unnecessary:

This is definitely a place for optimization - here it costs ~2 seconds just to do the auth and then throw it away.

2. Global setup

Playwright supports global setup/teardown scripts as an alternative to dependency projects. But this approach is not recommended, because it lacks many features of the Playwright runner. The only reason to use global scripts is if you don't want to introduce an extra project in the Playwright config.

✅ Advantages:

No extra project
Authentication runs only once

❌ Downsides:

Lacks features of the Playwright runner (fixtures, tracing, etc.)
Authentication steps are not visible in the report
Authentication always runs, even if not needed

3. BeforeAll

The 3rd option is to leverage the BeforeAll hook to perform authentication specifically for the auth.spec.ts. It runs conditionally only when at least one test of this suite is executed:

// auth.spec.ts

test.beforeAll(() => {
  console.log('Authenticating...');
});

test('test authenticated page', () => { ... });

This is a more optimized approach compared to project dependencies. When I run auth.spec.ts, the hook executes:

npx playwright test "/auth.spec.ts"

When I run no-auth.spec.ts, the hook does not execute:

npx playwright test "/no-auth.spec.ts"

But here we face all the issues mentioned in the introduction quiz. Every time a test fails, a new worker will be started, triggering the BeforeAll hook:

The same re-runs will occur during parallelization and sharding.

✅ Advantages:

No extra project, code stays close to the test
Steps are visible in the report
Runs on-demand only when needed

❌ Downsides:

Runs once per worker - so it repeats in parallel mode or after failures

A "Global Cache" Solution

I like the BeforeAll approach because it keeps the Playwright config simple and looks natural: run some code before all tests. But the problem is repeated execution per worker.

A year ago, I made my first attempt to solve this problem. Since then, it has grown into Global Cache - a helper module that ensures code runs only once across all workers.

The idea is simple:

The first worker that requests a value becomes responsible for computing it. Others wait until the result is ready — and all workers get the same value. The value is cached and reused by later workers.

Here's a diagram of how it works:

Under the hood, Global Cache spins up a tiny HTTP server, with a simple REST API for getting and setting values. This server is a single storage point for all workers. When a worker needs a value, it performs a GET request to the server, and either gets a cached value instantly or computes the value and sets it via the POST request.

Once integrated into Playwright test, Global Cache resolves the downside of the BeforeAll hook, ensuring the code runs exactly once. The API is wrapped into a globalCache interface with convenient methods:

import { globalCache } from '@global-cache/playwright';

test.beforeAll(async () => {
  const value = await globalCache.get('key', async () => {
    /* ...heavy calculation, runs once */
    return value;
  });
});

Actual code for the authentication in the BeforeAll hook:

// auth.spec.ts
import { test } from '@playwright/test';
import { globalCache } from '@global-cache/playwright';

let storageState;

test.beforeAll(async ({ browser }) => {
  storageState = await globalCache.get('storage-state', async () => {
    console.log('Authentication...');
    const page = await browser.newPage();
    // authentication steps...

    return page.context().storageState();
  });
});

// Set storageState fixture
test.use({ storageState: async ({}, use) => use(storageState) });

test('test authenticated page 1', () => { ... });
test('test authenticated page 2', () => { ... });
test('test authenticated page 3', () => { ... });

If any test fails or runs in parallel, the authentication will still run only once:

You might not need BeforeAll

The most interesting insight is that the BeforeAll hook becomes redundant! As the code is guaranteed to run once, no matter where to put it. I can move the authentication steps directly into the storageState fixture (that runs before each test!). This makes the code simpler:

// auth.spec.ts
import { test } from '@playwright/test';
import { globalCache } from '@global-cache/playwright';

test.use({ 
  storageState: async ({ browser }, use) => {
    const storageState = await globalCache.get('storage-state', async () => {
      const page = await browser.newPage();
      // authentication steps...
      return page.context().storageState();
    });
    await use(storageState);
  }
});

test('test authenticated page', () => { ... });

Note that for creating a page for authentication, I use the browser.newPage() call. If I try to use the built-in page fixture, I get a circular loop error because the page fixture depends on storageState.

Multiple files with conditional auth

In case of multiple authentication test files, you can move the auth logic into test.extend() to apply by default. Particular scenarios can be excluded by tags:

// fixtures.ts
import { test as baseTest } from '@playwright/test';
import { globalCache } from '@global-cache/playwright';

export const test = baseTest.extend({
  storageState: async ({ storageState, browser }, use, testInfo) => {
    // Skip authentication for '@no-auth'-tagged tests
    if (testInfo.tags.includes('@no-auth')) return use(storageState);

    storageState = await globalCache.get('auth-state', async () => {
      // authentication steps...
    });

    await use(storageState);
  },
});

Now I can use this test instance to run authenticated tests:

// auth.spec.ts
import { test } from './fixtures';

test('test authenticated page', () => { ... });

For non-authenticated tests I just add @no-auth tag:

// no-auth.spec.ts
import { test } from './fixtures';

test('test non-authenticated page', { tag: '@no-auth' }, () => { ... });

Recap

Global Cache keeps the simplicity of the BeforeAll hook but removes its biggest drawback: repeated execution in every worker. It lets you run any setup code exactly once across all workers, even in parallel mode or with sharding. It works not only for authentication, but also for database seeding, expensive API calls, or any other shared setup. You can find all these examples in the project repo.

Feel free to try it out and share any feedback.

Thanks for reading ❤️

Fix the Most Annoying MS Teams Bug: Reveal Hidden Tabs While Presenting

Vitaliy Potapov — Wed, 14 May 2025 14:27:23 +0000

🤯 The Problem: Teams Toolbar Hides Your Tabs

If you ever share your screen in Microsoft Teams, you’ve probably run into this: the floating presenter toolbar sits right on top of your browser tabs — hiding them completely.

Every time I present, I find myself stuck. I can’t switch to the tabs I need. Super frustrating.

🤔 Why Existing Workarounds Don’t Cut It

Click the toolbar and press Ctrl+W — but you have to remember the shortcut every time instead of focusing on the presentation.
Dragging the toolbar somewhere else — but then it’s floating awkwardly over the page, covering content and getting in the way.

🛠️ My Simple Fix: A Tiny Chrome Extension

So I made a tiny extension that just shifts the browser window down to reveal the tabs — nothing fancy.

🔽 Click the icon → window resizes below the toolbar
🔼 Click again → window restores to full height

Hear's the demo:

That’s it. No permissions, just a small fix for a niche problem.

🔗 Try It Out

You can try it yourself by the link: https://chromewebstore.google.com/detail/reveal-tabs-under-ms-team/iflklfjlpkkbdcigkfcpiendkiopeaeo

Happy to hear any feedback or suggestions — hope it helps someone else who presents regularly via Teams.

Open bookmarks in a new tab by default — easier said than done

Vitaliy Potapov — Thu, 01 May 2025 09:51:22 +0000

“I just want my Chrome bookmarks to open in a new tab by default.”

Sounds like a trivial feature, right? As it turns out, implementing this required a deep dive into Chrome APIs, creative hacks, and a journey full of unexpected roadblocks.

In this post, I’ll walk you through how I developed the Chrome extension Open bookmarks in a new tab. What seemed like a two-line tweak — turned out to be a rather tricky challenge, that required a non-trivial and inventive solution.

🧩 The Problem: Why Isn’t This a Built-In Feature?

The goal was simple: prevent the current tab from being replaced when I click on a bookmark. I just wanted Chrome to open bookmarks in a new tab by default.

Searching for “open bookmarks in a new tab” revealed tons of questions on Reddit, SuperUser, and Google Help forums. Clearly, this is something many users want (1, 2, 3).

The usual answers are:

“Just Ctrl + Click!”
“Middle-click the bookmark!”

Sure, those work — if you remember. But if you forget, you lose your current page’s context — scroll position, form data, or even unsaved work. That’s frustrating.

Another workaround is to use javascript: URLs in your bookmarks:

https://dev.to → javascript:window.open("https://dev.to")

This opens the bookmark in a new tab, yes — but at a cost:

❌ You lose the favicon (it defaults to the generic globe icon):
❌ javascript: links don’t run on internal pages like chrome://extensions (which is especially annoying if you’re developing Chrome extensions 🤪).

So I started digging into the Chrome Extensions API to find a better way.

🔍 First Attempt: Capture Bookmark Navigation

My initial idea:

Detect when a tab navigates due to a bookmark click.
Open that URL in a new tab.
Use chrome.tabs.goBack() to return the current tab to its previous state.

chrome.webNavigation.onCommitted.addListener(details => {
  if (details.transitionType === "auto_bookmark") {
    chrome.tabs.goBack(details.tabId);
    chrome.tabs.create({ url: details.url });
  }
});

It kind of worked. But it had a major flaw — the current tab does reload, and any page state is lost. This meant scroll positions, form inputs, or any unsaved data could be wiped out. Not acceptable.

💡 The Breakthrough: Downloads Instead of Navigation

After some thinking, I had an insight.

What if bookmarks triggered a download instead of a navigation?

If the page initiated a download, the current tab wouldn't change. And Chrome Extensions can detect and cancel downloads — avoiding any visual download animation.

So I created a dummy file empty.zip and added it to the extension. Then I created a bookmark that pointed to that file inside the extension.

chrome.downloads.onCreated.addListener((downloadItem) => {
  // capture download of chrome-extension://xxxxx/empty.zip
  if (downloadItem.url === chrome.runtime.getURL('/empty.zip')) {
    chrome.downloads.cancel(downloadItem.id);
    // Now open a new tab with the original URL
  }
});

And it worked! 🎉

✅ Current tab remained untouched.
✅ The download was captured and instantly canceled.
✅ No download animation in Chrome UI.

However, two issues emerged:

The bookmark's favicon changed to the extension’s icon — back to the favicon problem again.
I needed to know the original URL the user wanted to visit. But now all I had was /empty.zip.

So the question became: how can I preserve the original URL, trigger a dummy download, and still keep the favicon?

🕸️ Attempted Tricks: Redirects, Fragments, and More

My next idea: keep the original URL in the bookmark, but redirect it internally using chrome.declarativeNetRequest.

{
  "id": 1,
  "priority": 1,
  "condition": {
    "regexFilter": "????",
    "resourceTypes": ["main_frame"]
  },
  "action": {
    "type": "redirect",
    "redirect": {
      "extensionPath": "/empty.zip"
    }
  }
}

With this, when a user clicks a bookmark, the navigation would be silently redirected to empty.zip. The downloadItem object had both url and finalUrl, so I could recover the original URL to open in a new tab:

{
  "id": 563,
  "url": "https://dev.to/"
  "finalUrl": "chrome-extension://xxxxxx/empty.zip",
  // ...
}

But the problem? Every navigation to this URL downloads empty.zip. I had no way to tell which navigations came from bookmarks.

❌ Fragments Don’t Work

I tried appending a hash:

https://dev.to#newtab

But URL fragments don’t reach the network stack — so declarativeNetRequest ignores them. No help there.

❌ Custom Hostnames? Nope.

I considered using something like:

about:blank?https://dev.to

But again — doing this broke the favicon. Back to the default globe.

I was stuck. I needed a URL that would both initiate a ZIP file download and open in the browser to retrieve the correct favicon. It turned out to be a sort of Schrödinger's URL!

🧙 The Hack That Worked: Username in URL

Then I remembered something from the HTTP spec: URLs can contain a username/password for basic auth.

https://username:password@host.com

This pattern is rarely used today. Most servers ignore the credentials entirely.

What if I use the username field to mark the bookmark as special?

For example (password is omitted):

https://newtab@dev.to

✅ Chrome displays the original favicon.
✅ Most websites ignore the newtab@ part.
✅ The username field does get passed to declarativeNetRequest.

Bingo! This gave me a unique marker to trigger a redirect to empty.zip.

🏗️ Final Architecture

Here’s how the extension works end-to-end:

Every bookmark URL is rewritten with a username newtab:
- https://dev.to → https://newtab@dev.to
Any request with username newtab gets redirected to empty.zip.
When empty.zip download is triggered, the extension immediately cancels it and opens the original URL in a new tab.
Result: The original tab stays untouched. A new tab opens with the target URL. And the favicon is preserved:

💤 The Wakeup Problem

Everything worked beautifully in development. But when testing the production build, a new issue appeared.

After a period of browser inactivity, Chrome suspends background workers in extensions. So when the bookmark is clicked, the extension isn't awake in time to capture the download — and Chrome starts showing a download animation.

To fix this, I added a background alarm to wake the extension every 30 seconds:

chrome.alarms.create('keepAlive', { periodInMinutes: 0.5 });
chrome.alarms.onAlarm.addListener(() => {
  // no-op to keep the background alive
});

This keeps the downloads listener ready and prevents any flicker or download animation.

⚠️ Known Limitations

This hacky-yet-functional solution has some caveats:

Internal URLs don’t work. chrome:// or chrome-extension:// URLs can’t include a username. Demo code:

  const url = new URL('chrome://extensions/');
  url.username = 'newtab';
  console.log(url.href); // → 'chrome://extensions/'

So bookmarks pointing to internal pages still open in the same tab. However, you can still open them in a new tab by Ctrl + Click.

🎉 Conclusion

What started as a “5-minute side project” turned into a deep exploration of browser behavior, HTTP spec quirks, and extension APIs.

The final solution may look over-engineered — and it kind of is — but it works reliably, preserves user state, and doesn't break UX.

You can try the extension yourself: Open Bookmarks in a New Tab

And if you’re building Chrome extensions yourself, hopefully this journey helps you think outside the box (or at least inside the username part of the URL 😉).

[Boost]

Vitaliy Potapov — Thu, 13 Mar 2025 10:59:23 +0000

Request-Mocking-Protocol: A New Approach to Mocking Server-Side Requests in E2E Testing

Vitaliy Potapov ・ Mar 13

#playwright #testing #javascript #webdev

Request-Mocking-Protocol: A New Approach to Mocking Server-Side Requests in E2E Testing

Vitaliy Potapov — Thu, 13 Mar 2025 10:44:43 +0000

In modern web development, end-to-end testing is essential for ensuring that applications behave as expected. When using new features like React Server Components, we often rely on third-party APIs to fetch data on the server. While this approach offers significant benefits for performance and scalability, it can also introduce challenges for testing. Live API responses may change over time, causing tests to fail even when the application logic remains correct.

In this article, I'll introduce a new approach to server-side API mocking that makes tests fast and reliable with minimal setup. As a tech stack, I will use Playwright and Next.js, though the method works with any framework or test runner. Let’s dive in!

The Problem: Testing Server-Side Data Fetching

Consider the following server component, that fetches and renders a list of users from a third-party API:

export async function UserList() {
  const res = await fetch('https://jsonplaceholder.typicode.com/users');
  const users = await res.json();

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

When browser requests this page, the server performs a subsequent call to /users API and returns rendered HTML:

The page in the browser:

A basic Playwright test might look like this:

test('show user list', async ({ page }) => {
  await page.goto('/');

  await expect(page.getByRole('listitem').first()).toHaveText('Leanne Graham');
});

This test passes when the first item in the API response is Leanne Graham. But what happens if the API returns a different order or data? The test will fail even though the application itself is functioning correctly.

Example of failed test, when elements are returned in a reversed order:

The test would be more reliable, if it could mock the GET /users request and provide a static list of users:

When requests are made from the browser context, Playwright's API mocking feature works fine. However, this approach doesn't intercept server-side requests.

Existing Approaches

Several efforts have been made to address this challenge:

Playwright Proxy Approach

An in-progress pull request in the Playwright repo introduces server-side mocking by running an HTTP proxy alongside the test process. The app is configured to route outgoing requests through this proxy. If a request matches a specified URL pattern, a user-defined handler applies the mock response.

While this approach is highly flexible, it also presents challenges. For instance, if your app is deployed on platforms like Vercel and tests run in GitHub workflows, setting up a tunnel to connect the app to the proxy can be complex and error-prone.

Mock Service Worker (MSW)

MSW is a popular tool for mocking HTTP requests. It is also working on server-side mocking support, as seen in this pull request. Instead of using an HTTP proxy, MSW relies on WebSockets as a transport layer to address connectivity issues:

However, this approach has its own limitations, as noted in the pull request:

You cannot have multiple tests that override request handlers for the same app at the same time.

This means that tests with server-side mocks cannot run in parallel, which is a major drawback for end-to-end testing.

Overall, existing approaches aim to use an arbitrary function as the mocked request handler but introduce connectivity and parallelization challenges.

Proposed Solution

While experimenting with these solutions, I came to a simpler idea:

What if we pass the mocking data within the navigation request using a custom HTTP header?

How It Works

Embed Mock Data: Instead of routing server-side requests through an external proxy, we encode static mock responses as JSON and attach them in a custom header (e.g., x-mock-request).
Server-Side Parsing: On the server, we intercept outgoing API calls, read the custom header, and apply the corresponding mock if the request matches the predefined schema.

This approach solves both the connectivity and parallelization issues:

There’s no need to set up tunnels or spin a separate proxy server.
Each test can pass its own mock data via HTTP headers without conflict.

Of course, there are limitations:

Static Data Only: The mock must be serializable to JSON. This means you can only provide static responses (e.g., { status: 200, body: 'Hello' }) rather than dynamic, function-based mocks.
Header Size Limits: HTTP headers typically support 4KB to 8KB of data. This approach is best suited for small payloads.

In many real-world scenarios, these limitations are acceptable. Most mocks are lightweight and static, making this a practical solution for ensuring test stability.

Implementation

Below is a step-by-step guide how to implement this solution with Playwright and Next.js.

Define Schemas

First, define the schemas for the request and the response. For instance, to mock a server-side GET request to https://jsonplaceholder.typicode.com/users, you can set up the following:

Request Schema:

const reqSchema = {
  method: 'GET', 
  url: 'https://jsonplaceholder.typicode.com/users',
};

Response Schema:

const resSchema = {
  status: 200,
  body: [
    { id: 1, name: 'John Smith' }
  ]
};

Combine Schemas and Build the Header:

const mockSchema = { reqSchema, resSchema };
const mockSchemaString = JSON.stringify(mockSchema);
const headers = {
  'x-mock-request': mockSchemaString
};

Playwright Integration

To attach custom HTTP headers to the navigation request, use Playwright's page.setExtraHTTPHeaders:

test('show user list', async ({ page }) => {
  await page.setExtraHTTPHeaders({
    'x-mock-request': mockSchemaString
  });

  await page.goto('/');
});

With this configuration, every navigation and subsequent request from the page will include the mocking header.

Handling on the Server

On the server side, the following steps are required:

Read incoming headers
Get x-mock-request value and extract mock schemas
Intercept outgoing request
Apply mock schemas and return the mocked response

Read Incoming Headers and Extract Schemas

To read the incoming headers, you can use Next.js's headers() helper. When x-mock-request header is found, use JSON.parse() to extract mock schemas:

import { headers } from 'next/headers';

// ...

const headersList = await headers();
const mockHeader = headersList.get('x-mock-request');
const mockSchemas = JSON.parse(mockHeader);

Intercept Outgoing Requests

To intercept all outgoing requests in Next.js app, you can overwrite the globalThis.fetch function:

const originalFetch = globalThis.fetch;
globalThis.fetch = async (input, init) => {
  // inspect and potentially mock outgoing request
};

Inside the intercepted function, you can read the incoming headers and apply the mocks. Full code of the function:

function interceptGlobalFetch() {
  const originalFetch = globalThis.fetch;
  globalThis.fetch = async (input, init) => {
    // Read incoming headers and extract mocks
    const headersList = await headers();
    const mockHeader = headersList.get('x-mock-request');
    const mockSchemas = JSON.parse(mockHeader);

    // Match the request against schemas
    const request = new Request(input, init);
    const matchedSchema = mockSchemas.find(schema => matchRequest(request, schema));

    // Return mocked response or make a real request
    return matchedSchema
      ? buildMockedResponse(request, matchedSchema)
      : originalFetch(request)
  };
}

The global fetch should be instrumented at server startup, before any requests are made. Next.js provides a dedicated file for this task, called instrumentation.js:

// instrumentation.js

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs' && process.env.NODE_ENV !== 'production') {
    interceptGlobalFetch();
  }
}

Note: Interception should be enabled only in the nodejs runtime and in non-production environments.

Testing the Whole Flow

Once the server-side interception is in place, you can run your Playwright test with the server-side mock. Here’s an example:

test('show user list', async ({ page }) => {
  // Set up server-side mock
  await page.setExtraHTTPHeaders({
    'x-mock-request': buildMockHeader()
  });

  // Navigate to the page
  await page.goto('/');

  // Assert page content according to mock data
  await expect(page.getByRole('listitem').first()).toHaveText('John Smith');
});

The buildMockHeader() helper just combines request and response schemas:

function buildMockHeader() {
  const reqSchema = {
    method: 'GET', 
    url: 'https://jsonplaceholder.typicode.com/users',
  };

  const resSchema = {
    status: 200,
    body: [
      { id: 1, name: 'John Smith' }
    ]
  };

  return JSON.stringify([ { reqSchema, resSchema } ]);
}

Running the test:

> npx playwright test

Running 1 test using 1 worker
  1 passed (1.3s)

The page's screenshot shows a list with a mocked data - a single user John Smith:

With such a mock, the test no longer depends on the API response while ensuring that the server component correctly renders the data.

Wrapping into a Library

To reduce the boilerplate code for server-side mocking, I bundled the functionality into a separate package called request-mocking-protocol. It hides the implementation details and provides a friendly API for setting up mocks on client and server side.

Example Usage with the Library

The following example demonstrates how to use the library in a Playwright test:

test('show user list', async ({ page, mockServerRequest }) => {
  // Set up server-side mock
  await mockServerRequest.GET('https://jsonplaceholder.typicode.com/users', {
    body: [{ id: 1, name: 'John Smith' }],
  });

  // Navigate to the page
  await page.goto('/');

  // Assert page content according to mock data
  await expect(page.getByRole('listitem').first()).toHaveText('John Smith');
});

The custom fixture mockServerRequest is defined as follows:

import { test as base } from '@playwright/test';
import { MockClient } from 'request-mocking-protocol';

export const test = base.extend({
  mockServerRequest: async ({ context }, use) => {
    const mockClient = new MockClient();
    mockClient.onChange = async (headers) => context.setExtraHTTPHeaders(headers);
    await use(mockClient);
  },
});

Under the hood, the library builds the mocking schemas and exposes them as HTTP headers.

On the server, you can set up the interceptor with a single call of setupFetchInterceptor():

// instrumentation.js
import { headers } from 'next/headers';

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs' && process.env.NODE_ENV !== 'production') {
    const { setupFetchInterceptor } = await import('request-mocking-protocol/fetch');
    setupFetchInterceptor(() => headers());
  }
}

Recap

In this article, I introduced an alternative approach to server-side request mocking that uses HTTP headers to transfer mock data. This setup is simpler because it eliminates the need for additional proxies. Each test carries its own mock data, allowing for parallel execution and improved scalability.

The approach does have some limitations. It only supports static mocks — arbitrary JavaScript functions are not allowed. Additionally, HTTP headers have size limits, making this method best suited for smaller payloads.

Despite these trade-offs, the solution looks promising. I've packaged it into a library for easier integration with different frameworks. You are welcome to give it a try and share the feedback.

Thanks for reading, and happy testing ❤️

"Fix with AI" Button in Playwright HTML Report

Vitaliy Potapov — Mon, 13 Jan 2025 18:01:13 +0000

Introduction

End-to-end tests are great for ensuring application reliability, but they can bring maintenance headaches. Even minor UI changes can break tests, leaving developers and QAs wasting hours debugging.

In this article, I’ll show you how to leverage ChatGPT or Copilot to fix Playwright tests automatically. You’ll learn how to pre-generate an AI prompt for any failing test and attach it to the HTML report. That way, you can easily copy and paste the prompt into AI tools and instantly get suggestions for fixing the test.

Let’s dive in!

Plan

The solution boils down to three steps:

Detect when a Playwright test fails
Generate an AI prompt with relevant context:
- Error message
- Test code snippet
- ARIA snapshot of the page
Attach the prompt to the Playwright HTML report

Step 1: Detecting a Failed Test

Detecting a failed test in Playwright can be done in a custom fixture. This fixture inspects the test result in the teardown phase (after the test finishes). If a test has testInfo.error and will not be retried, a prompt is generated.

Here’s the code snippet:

import { test as base } from '@playwright/test';

export const test = base.extend({
  fixWithAI: [async ({ page }, use, testInfo) => {
    await use();
    const willBeRetried = testInfo.retry < testInfo.project.retries;
    if (testInfo.error && !willBeRetried) {
      // ... build a prompt to fix the error
      // ... attach the prompt to the test
    }
  }, { scope: 'test', auto: true }],
});

Step 2: Building the Prompt

Prompt Template

I start with a simple proof-of-concept prompt (will refine it later):

Fix the error in the Playwright test "{title}". 

{error}

Code snippet of the failing test:

{snippet}

ARIA snapshot of the page:

{ariaSnapshot}

Let’s fill the prompt with the necessary data.

Error Message

Playwright stores the error message in testInfo.error.message. However, it includes special ASCII control codes for coloring output in the terminal (such as [2m or [22m):

TimeoutError: locator.click: Timeout 1000ms exceeded.
Call log:
[2m  - waiting for getByRole('button', { name: 'Get started' })[22m

After investigating Playwright’s source code, I found a stripAnsiEscapes function that removes these special symbols:

const clearedErrorMessage = stripAnsiEscapes(testInfo.error.message);

Cleared error message:

TimeoutError: locator.click: Timeout 1000ms exceeded.
Call log:
  - waiting for getByRole('button', { name: 'Get started' })

This cleaned-up message can be inserted into the prompt template.

Code Snippet

The test code snippet is crucial for AI to generate the necessary code changes. Playwright often includes these snippets in its reports, for example:

  4 | test('get started link', async ({ page }) => {
  5 |   await page.goto('https://playwright.dev');
> 6 |   await page.getByRole('button', { name: 'Get started' }).click();
    |                                                           ^
  7 |   await expect(page.getByRole('heading', { level: 3, name: 'Installation' })).toBeVisible();
  8 | });

You can see how Playwright internally generates these snippets. I've extracted the relevant code into a helper function, getCodeSnippet(), to retrieve the source code lines from the error stack trace:

const snippet = getCodeSnippet(testInfo.error);

The full code for getCodeSnippet() is here.

ARIA Snapshot

ARIA snapshots, introduced in Playwright 1.49, provide a structured view of the page’s accessibility tree. Here’s an example ARIA snapshot showing the navigation menu on the Playwright homepage:

- document:
  - navigation "Main":
    - link "Playwright logo Playwright":
      - img "Playwright logo"
      - text: Playwright
    - link "Docs"
    - link "API"
    - button "Node.js"
    - link "Community"
  ...

While ARIA snapshots are primarily used for snapshot comparison, they are also a game-changer for AI prompts in web testing. Compared to raw HTML, ARIA snapshots offer:

Small size → Less risk of hitting prompt limits
Less noise → Less unnecessary context
Role-based structure → Encourages AI to generate role-based locators

Playwright provides .ariaSnapshot(), which you can call on any element. For AI to fix a test, it makes sense to include the ARIA snapshot of the entire page, retrieved from the root <html> element:

const ariaSnapshot = await page.locator('html').ariaSnapshot();

Assembling the Prompt

Finally, combine all the pieces into one prompt:

const errorMessage = stripAnsiEscapes(testInfo.error.message);
const snippet = getCodeSnippet(testInfo.error);
const ariaSnapshot = await page.locator('html').ariaSnapshot();

const prompt = promptTemplate
  .replace('{title}', testInfo.title)
  .replace('{error}', errorMessage)
  .replace('{snippet}', snippet)
  .replace('{ariaSnapshot}', ariaSnapshot);

Example of the generated prompt:

Fix the error in the Playwright test "get started link". 

TimeoutError: locator.click: Timeout 1000ms exceeded.
Call log:
  - waiting for getByRole('button', { name: 'Get started' })

Code snippet of the failing test:

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await page.getByRole('button', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

ARIA snapshot of the page:

- document:
  - region "Skip to main content":
    - link "Skip to main content"
  - navigation "Main":
    - link "Playwright logo Playwright":
      - img "Playwright logo"
      - text: Playwright

  ...

Step 3: Attach the Prompt to the Report

When the prompt is built, you can attach it to the test using testInfo.attach:

await testInfo.attach('🤖 Fix with AI', { body: prompt });

Now, whenever a test fails, the HTML report will include an attachment labeled “🤖 Fix with AI.”

Testing

To try out the "Fix with AI" prompt, I created a simple test to validate the Get started link on the Playwright homepage:

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

When it’s correct, the test passes:

$ npx playwright test

Running 1 test using 1 worker
  1 passed (1.9s)

Next, I’ll introduce deliberate errors and see how the AI prompt can help.

Check 1: Changing the Role from `link` to `button`

Suppose we introduce a bug by modifying the test locator's role from link to button:

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev');
-  await page.getByRole('link', { name: 'Get started' }).click();
+  await page.getByRole('button', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

The test now fails. In the Playwright HTML report, you’ll see a new attachment labeled “🤖 Fix with AI”:

HTML report with AI prompt attachment

You can expand the attachment and copy the prompt by clicking the small button in the top-right corner:

Copying the prompt

Pasting the prompt into ChatGPT yields a suggested fix:

ChatGPT output for fixing the test

ChatGPT correctly identifies that the button role is incorrect and recommends using a link role. After applying the suggestion, the test passes! 🎉

Improving the Prompt

Although ChatGPT gave a detailed explanation, in day-to-day workflows, you might prefer a more concise output that focuses on code changes. I've made many experiments and arrived at this prompt template:

You are an expert in Playwright testing. 
Fix the error in the Playwright test "{title}".

- Provide response as a diff highlighted code snippet.
- Strictly rely on the ARIA snapshot of the page.
- Avoid adding any new code.
- Avoid adding comments to the code.
- Avoid changing the test logic.
- Use only role-based locators: getByRole, getByLabel, etc.
- For 'heading' role try to adjust the level first.
- Add a concise note about applied changes.
- If the test may be correct and there is a bug in the page, note it.

{error}

Code snippet of the failing test:

{snippet}

ARIA snapshot of the page:

{ariaSnapshot}

With this refined prompt, ChatGPT usually provides a succinct fix. You simply copy the suggested code and paste it back into your test:

Updated ChatGPT output

I now use this new prompt for the following checks.

Check 2: Adjust Link Text

In this scenario, the UI text has changed - a very common case for real projects. The link has changed from Get started to Get involved:

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev');
- await page.getByRole('link', { name: 'Get started' }).click();
+ await page.getByRole('link', { name: 'Get involved' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

The test will fail. ChatGPT, using the ARIA snapshot, can detect the text mismatch and suggest updating the locator’s name property:

ChatGPT fixes link text

It’s important to distinguish actual bugs from legitimate UI text changes. That’s why I prefer to see the code diff first and analyze what’s happening.

Check 3: Remove Link Name

What if the locator matches multiple elements on the page? Let’s test if AI can identify the correct one.

I remove the link’s name property, causing the locator to match all links on the page:

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev');
- await page.getByRole('link', { name: 'Get started' }).click();
+ await page.getByRole('link').click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

The test fails with:

Error: locator.click: Error: strict mode violation: 
getByRole('link') resolved to 39 elements:

ChatGPT’s suggestion:

ChatGPT detects the correct link element

This is fantastic! Among 39 links on the page, ChatGPT pinpoints the correct one. Providing the test title and code snippet really helps AI figure out the right fix.

It also suggests adjusting the heading level for the "Installation" check to make the locator more reliable.

All these checks confirm that AI-powered prompts significantly reduce the time spent fixing tests. You get direct code suggestions that you can easily apply.

Using Copilot Edits

When using ChatGPT to fix tests, you must manually apply the suggested changes. You can streamline this step by using Copilot. Instead of pasting the prompt into ChatGPT, open the Copilot edits window in VS Code and paste your prompt there. Copilot will propose code changes that you can review and apply instantly—all within your editor.

Here’s a demo video of fixing a test with Copilot in VS Code:

Further Improvements

This AI-driven approach can be refined further. Here are some ideas I’m excited about:

1. "Fix with AI" Button in the Playwright VS Code Extension

Right now, you have to manually copy and paste the generated prompt. Imagine a button in the Playwright VS Code extension that appears when a test fails, automatically sending the context to your AI tool. That would be ideal!

Here’s a mockup showing where the “Fix with AI” button could appear:

Potential place for "Fix with AI" button in Playwright VS Code extension

2. HTML Report Enhancements

Similarly, a button in the Playwright HTML report could automatically send a request to a configured AI model and display a suggested fix. This would be especially helpful for team members who focus on reports and don't use IDE.

Here’s a potential spot for a “Fix with AI” button in the report:

Potential place for "Fix with AI" button in Playwright HTML report

Unfortunately, Playwright HTML report doesn’t support such level of customization. These issues may pave the way, so feel free to vote for them:

Integrating “Fix with AI” into Your Project

I’ve created a fully working GitHub repository demonstrating the “Fix with AI” workflow. Feel free to explore it, run tests, check out the generated prompts, and fix errors with AI help.

To integrate the “Fix with AI” flow into your own project, follow these steps:

Ensure you’re on Playwright 1.49 or newer
Copy the fix-with-ai.ts file into your test directory

import { test as base } from '@playwright/test';
import { attachFixWithAI } from './fix-with-ai';

export const test = base.extend<{ fixWithAI: void }>({
  fixWithAI: [async ({ page }, use, testInfo) => {
    await use();
    await attachFixWithAI(page, testInfo);
  }, { scope: 'test', auto: true }],
});

Run your tests and open the HTML report to see the “Fix with AI” attachment under any failed test

From there, simply copy and paste the prompt into ChatGPT or GitHub Copilot, or use Copilot’s edits mode to automatically apply the code changes.

I’d love to hear your thoughts or prompt suggestions for making the “Fix with AI” process even more seamless. Feel free to share your feedback in the comments.

Thanks for reading, and happy testing with AI! ❤️

Show Metadata in Playwright HTML Report: A Complete Guide

Vitaliy Potapov — Thu, 19 Dec 2024 18:06:14 +0000

Playwright is a powerful testing framework, but its HTML reports can feel bare-bones for complex projects. Wouldn't it be nice to display metadata such as commit messages, author details, or links to CI builds right in the report header? Here's how to achieve that and some deeper insights into Playwright's capabilities.

Understanding Playwright Metadata

The Playwright documentation mentions a metadata field for configuration:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  metadata: 'acceptance tests',
});

At the time of writing (Playwright v1.49), it states:

Metadata that will be put directly into the test report serialized as JSON

But there's a catch: adding this configuration won't show any metadata in the report. If you're using TypeScript, you'll also see an error for the provided example:

Type 'string' is not assignable to type 'Metadata'.

Clearly, the documentation is outdated, but metadata in reports is indeed possible.

The Real Metadata Configuration

After diving into Playwright’s source code, I discovered the actual fields supported by the HTML report:

export type Metainfo = {
  'revision.id'?: string;
  'revision.author'?: string;
  'revision.email'?: string;
  'revision.subject'?: string;
  'revision.timestamp'?: number | Date;
  'revision.link'?: string;
  'ci.link'?: string;
  'timestamp'?: number;
};

Only these fields can be displayed. Let’s configure them in playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: 'html',
  metadata: {
    'revision.id': 'adcb0c51debdbe96a6a836e2ead9d40a859f6438',
    'revision.author': 'John Smith',
    'revision.email': 'john.smith@gmail.com',
    'revision.subject': 'Acceptance tests',
    'revision.timestamp': Date.now(),
    'revision.link': 'https://github.com/microsoft/playwright/pull/12734',
    'ci.link': 'https://github.com/microsoft/playwright/actions/workflows/tests_primary.yml',
    'timestamp': Date.now(),
  },
});

After running tests, the HTML report header displays this metadata beautifully.

Automating Metadata Population

Manually filling metadata fields isn't practical, especially in dynamic environments like CI/CD pipelines. Automating this process ensures accurate and consistent metadata without manual effort.

Third-Party packages

To automate the process, you can utilize any third-party package that extracts Git commit information. This is a straightforward approach, let's proceed to the second option that is more interesting.

Leveraging Playwright’s Hidden Plugin System

One of the most intriguing discoveries about Playwright is its hidden plugin system. While not officially documented, it provides a way to extend Playwright's capabilities through custom plugins.

I've got this insight while looking as the test of Playwright itself. Playwright supports a hidden configuration field "@playwright/test", where you can define plugins.

Here’s an example of enabling the gitCommitInfo plugin:

import { defineConfig } from '@playwright/test';
import { gitCommitInfo } from 'playwright/lib/plugins';

export default defineConfig({
  reporter: 'html',
  // @ts-expect-error
  '@playwright/test': { 
    plugins: [gitCommitInfo()] 
  },
});

What Does the `gitCommitInfo` Plugin Do?

This plugin extracts Git commit details and populates metadata fields in the HTML report, including:

Commit hash
Commit message
Author name and email
Timestamp

Additionally, when run in CI/CD environments, the plugin can automatically populate fields using standard environment variables like GITHUB_SHA or CI_COMMIT_SHA.

After enabling the plugin and running tests, I've got the following report with metadata automatically filled:

Other Plugins

I was curious, are there any other hidden plugins in Playwright?
In the plugins directory there is only one more plugin - webServerPlugin. It allows to start and stop built-in web server when running tests. In fact, when you define config.webServer option, this plugin is used under the hood. So the Plugin system is internally used in Playwright, although is not documented for public usage.

The plugin system was introduced in earlier versions of Playwright, but was hidden as some point. Unfortunately, there are no plans to expose it as of now.

Using a Custom Function for Metadata

If you'd rather auto-fill metadata without relying on plugins, you can do so with a custom function. I've adapted the gitStatusFromCLI() function from the gitCommitInfo plugin, making it usable independently:

import { spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';

const GIT_OPERATIONS_TIMEOUT_MS = 1500;

export const gitStatusFromCLI = (gitDir = process.cwd()) => {
    const separator = `:${randomUUID().slice(0, 4)}:`;
    const { status, stdout } = spawnSync(
        'git',
        ['show', '-s', `--format=%H${separator}%s${separator}%an${separator}%ae${separator}%ct`, 'HEAD'],
        { stdio: 'pipe', cwd: gitDir, timeout: GIT_OPERATIONS_TIMEOUT_MS }
    );
    if (status) return;
    const showOutput = stdout.toString().trim();
    const [id, subject, author, email, rawTimestamp] = showOutput.split(separator);
    let timestamp: number = Number.parseInt(rawTimestamp, 10);
    timestamp = Number.isInteger(timestamp) ? timestamp * 1000 : 0;

    return {
      'revision.id': id,
      'revision.author': author,
      'revision.email': email,
      'revision.subject': subject,
      'revision.timestamp': timestamp,
    };
  };

Usage of the function to populate metadata in the Playwright config:

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { gitStatusFromCLI } from './commitInfo';

export default defineConfig({
  reporter: 'html',
  metadata: gitStatusFromCLI()
});

After running tests, I've got the same HTML report with filled metadata:

This approach gives you full control over metadata automation without depending on internal Playwright features.

Optimizing for Parallel Tests

Everything looks good, but there is a performance issue with the code above. Could you guess what is the problem?

Playwright runs tests in workers. When each worker starts, it imports Playwright config. If Playwright config performs a heavy operation (like fetching Git data), it will slow down the worker. Moreover, there is no sense to execute the command many times, as it will return the same result.

You can optimize it by executing the metadata function only in the main worker. The main worker can be detected by empty TEST_WORKER_INDEX env variable:

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { gitStatusFromCLI } from './commitInfo';

const isMainWorker = !process.env.TEST_WORKER_INDEX;

export default defineConfig({
  reporter: 'html',
  metadata: isMainWorker ? gitStatusFromCLI() : undefined,
});

This ensures metadata is populated efficiently without affecting performance.

Conclusion

Adding metadata to Playwright HTML reports is possible, though not well-documented. You can manually configure metadata, leverage the hidden plugin system, or implement a custom solution.

Key Takeaways:

Metadata fields are limited to specific keys (revision.id, ci.link, etc.).
Automate metadata with Playwright’s hidden plugins or custom scripts.
Optimize for parallel tests by executing metadata logic only in the main worker.

Based on the research for the article, I've opened a pull-request to the Playwright repo, proposing documentation improvements for metadata field.

Have you tried adding metadata to Playwright reports? Share your experience or challenges in the comments!

Supercharge Your E2E Tests with Playwright-Network-Cache

Vitaliy Potapov — Tue, 08 Oct 2024 06:10:09 +0000

Intro

When working with end-to-end testing frameworks like Playwright, handling network requests is often a complex task. Tests that rely on external APIs can be slow and inconsistent, introducing unnecessary flakiness. Network calls that succeed in one test run might fail in the next due to a slow or unreliable server, resulting in inconsistent results. To address this, developers often resort to mocking network requests, which introduces another challenge: managing mocks.

Wouldn’t it be great to have an automated way to handle caching and reusing network responses without setting up complex mocking strategies? I've investigated existing approaches and developed a tool that I want to introduce. It solves these exact problems by caching network requests on the filesystem, enabling faster and more reliable Playwright tests.

The Problem with Network Requests in Tests

Network requests are often the slowest part of test execution. When running multiple test suites, the repeated querying of external APIs can dramatically increase test durations. Additionally, real-world APIs can be unstable, with occasional timeouts, making your tests fragile and unreliable.

A common approach to mitigating this is to mock API responses. While useful, mocking requires manual intervention — you need to carefully construct mock responses, keep them updated, and ensure that every potential network scenario is handled. This can become a huge maintenance burden as the API evolves or your test cases change. Playwright supports HAR files for capturing and replaying network traffic, but working with HAR can be tedious and lacks flexibility for modifying responses on the fly.

Enter `playwright-network-cache`

playwright-network-cache is designed to streamline the process of caching network responses in Playwright tests, eliminating the need for manual mocks or rigid HAR files. With this library, network responses are automatically stored on the filesystem during the first test run and can be reused in subsequent runs, significantly speeding up test execution. Moreover, the responses are saved in a clear, organized folder structure, making it easy to inspect and modify them as needed.

How It Solves the Problem

Automatic Caching: The library automatically caches network responses when tests are run for the first time. This means that your tests won't have to wait for external APIs to respond in future runs — the cached data will be used instead, resulting in faster and more reliable tests.
Customizable Cache Duration (TTL): You can control how long the cached file is retained by setting a time-to-live (TTL) option. After the specified time elapses, the library will hit real API again and refresh the cache, keeping your test data up to date.
Dynamic Modifications: Need to tweak a response for a specific test case? playwright-network-cache allows you to modify cached responses dynamically. Whether you want to change the status code, headers, or response body, the library provides options to adjust the cached data on-the-fly without manually maintaining separate mocks.
Flexible Structure: The caching system organizes files based on hostname, request method, and URL path, ensuring that you can easily navigate through and manage the cached data. For more complex cases, you can even split cache files by request query parameters, request bodies, or other custom fields, ensuring complete flexibility in how data is stored and reused.
Speed Boost: By reusing cached responses, your tests no longer need to wait for network calls to complete, making them dramatically faster. This is especially useful when working with large test suites or when running tests in CI environments where speed is critical.
No More Mock Hell: Forget about manually maintaining mocks. The library handles everything for you — from caching to replaying and even modifying responses. You’ll no longer need to manually craft mock responses for each test scenario, and you can focus more on your test logic.
No HAR Complexity: HAR files can be useful for recording and replaying network interactions, but they quickly become cumbersome, especially when you need to modify responses. playwright-network-cache provides a cleaner, more flexible alternative to HAR by letting you manage individual responses as simple JSON files.

Example

Imagine you're testing an application that fetches a list of cats from an API. Without caching, each test run would require a live request to the API, adding latency and potential failure points to your tests.

With playwright-network-cache, you can easily cache the API response:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('https://example.com/api/cats');
  // Perform usual test actions...
});

On the first run, the response is cached in the .network-cache directory, with a structure like this:

.network-cache
└── example.com
    └── api-cats
        └── GET
            ├── headers.json
            └── body.json

On subsequent runs, the cached response is reused, making the test faster and eliminating the need to hit the actual API.

To revalidate the cache, you can provide ttlMinutes option:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('https://example.com/api/cats', {
   ttlMinutes: 60 // hit real API once in a hour
  });
  // Perform usual test actions...
});

You can modify cached response for the particular test needs:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('https://example.com/api/cats', {
    modify: async (route, response) => {
      const json = await response.json();
      json[0].name = 'Kitty-1';
      await route.fulfill({ json });
    }
  });
  // Perform usual test actions...
});

To get cacheRoute variable available in your tests, instantiate it like any other Playwright fixture:

// fixtures.js
import { test as base } from '@playwright/test';
import { CacheRoute } from 'playwright-network-cache';

export const test = base.extend({
  cacheRoute: async ({ page }, use) => {
    const cacheRoute = new CacheRoute(page, { /* cache options */ });
    await use(cacheRoute);
  },
});

There are many other examples and use-cases in the library documentation.

More Than Just Caching

playwright-network-cache isn’t just about caching. It offers advanced features like:

Modifying Responses: Adjust the data in the cached responses dynamically using custom functions.
Handling Status Codes: Cache responses based on specific HTTP status codes, including errors.
Flexible Directory Structure: Customize how and where cache files are stored, allowing you to tailor caching strategies to your needs.
Disable or Update Cache: Temporarily disable caching for specific tests or force updates to the cache when needed.

With these powerful capabilities, you can finely control how network requests are managed in your tests.

Recap

If you're looking to make your Playwright tests faster and more reliable, give a try to playwright-network-cache. By caching network responses on the filesystem and allowing for dynamic modifications, it eliminates the need for manual mocks and provides a flexible, easy-to-use alternative to HAR files.

Thanks for reading ❤️

Setting up Subpath Import Aliases in a TypeScript Project

Vitaliy Potapov — Sun, 01 Sep 2024 17:23:27 +0000

TL;DR use custom conditions

One day, I decided to incorporate modern path aliases in my TypeScript project. I didn't expect it would be such a challenging journey! You are welcome to read the details ⏬

Content

Intro
Example Project
Attempt #1: Follow Node.js Docs
Attempt #2: Use dist instead of src
Attempt #3: Set rootDir and outDir
Attempt #4: Point to dist/src
Attempt #5: Custom Conditions to the Rescue
- Update TypeScript Configuration
- Update Vitest Configuration
- Other Tools
Recap

Intro

Subpath imports are a native feature in Node.js that allows to define aliases for internal paths in a codebase.

For example, instead of writing:

import { foo } from '../../../utils.js';

You can set up a subpath import to simplify this to:

import { foo } from '#utils.js';

Two main benefits:

easier to read
no extra diff after files move

In TypeScript, there is an older way for setting up aliases via paths option. Although it works fine for TypeScript itself, the problem is that Node.js is not aware of this config. You need to use third party packages to run compiled code (tsconfig-paths, tsc-alias).

Great news is that since v5.4 TypeScript added support for subpath imports. While the concept sounds straightforward, integrating subpath imports in my test project was tricky. I'll walk through all the issues step by step and share the final solution. Let's start.

Example Project

Imagine the following project structure:

my-project
├── src
│   ├── index.ts
│   └── utils.ts
├── test
│   └── index.spec.ts
├── package.json
├── tsconfig.build.json
├── tsconfig.json
└── vitest.config.mts

This is a fairly typical setup:

src and test contain the source code and unit tests respectively
tsconfig.json for type-checking the entire project
tsconfig.build.json for compiling the source code from src into the dist directory
vitest.config.mts for running unit tests with vitest

Initially, this project uses classic relative paths. src/index.ts imports constant foo from utils:

// src/index.ts
import { foo } from './utils.js';

console.log(foo);

// src/utils.ts
export const foo = 42;

In the test directory there is also import of utils by relative path:

// test/index.spec.ts
import { foo } from '../src/utils.js';

test('foo is 42', () => {
  expect(foo).toBe(42);
});

There are a few npm scripts in package.json, that successfully run in the initial project state:

  "scripts": {
    "tsc": "tsc",
    "test": "vitest run",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/index.js"
  }

npm run tsc - type-check the entire project
npm run test - run tests against the actual code in src
npm run build - compile the code from src into the dist directory
npm start - run the project from the dist directory

I will use these commands as a checklist to ensure everything works after setting up subpath imports.

Also, I will check in VSCode that CMD / CTRL + click on utils import navigates to the file contents.

Attempt #1: Follow Node.js Docs

My first step was to follow the samples from Node.js documentation. I've added an imports field to the package.json and set alias for the src directory.

// package.json
{
  "name": "subpath-imports-typescript",
+  "imports": {
+    "#*": "./src/*"
+  },
}

and used that alias in src/index.ts and test/index.spec.ts:

// src/index.ts
- import { foo } from './utils';
+ import { foo } from '#utils.js';

// test/index.spec.ts
- import { foo } from '../src/utils.js';
+ import { foo } from '#utils.js';

After making these changes, all commands worked except the npm start, which failed with the following error:

> node dist/index.js

node:internal/modules/cjs/loader:1110
        throw e;
        ^

Error: Cannot find module '/projects/subpath-imports-typescript/src/utils.js'

The problem occurred because Node.js was looking for the utils.js in the src directory instead of the dist directory. Since the project is meant to run from the dist directory, Node.js couldn’t find the required file.

Attempt #2: Use `dist` instead of `src`

To fix this, I adjusted the imports field in package.json to point to the dist directory instead of src:

{
  "name": "subpath-imports-typescript",
  "imports": {
-    "#*": "./src/*"
+    "#*": "./dist/*"
  },
}

Initially, this change seemed to work. However, once I deleted the dist directory, everything got broken! VSCode could no longer find the #utils.js module, and TypeScript showed an error:

Cannot find module '#utils.js' or its corresponding type declarations.

The root cause was that TypeScript and VSCode couldn’t resolve the alias because the files in the dist directory are missing.

A chicken-and-egg problem - source files refer compiled files to get compiled files 🤪

To address that issue TypeScript documentation recommends setting the rootDir and outDir options.

Attempt #3: Set `rootDir` and `outDir`

I've added the rootDir and outDir options to tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2021",
    "module": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts"]
}

The idea here is following: when TypeScript knows the source and destination directories of compiled files, it can re-map import aliases to the source location.

In my case, #utils.js will be first resolved to ./dist/utils.js and then re-mapped to ./src/utils.ts.

However, when I ran tsc, TypeScript threw the following error:

File '/xxx/subpath-imports-typescript/test/index.spec.ts' is not under 'rootDir' 
'/xxx/subpath-imports-typescript/src'. 'rootDir' is expected to contain all source files.

To resolve this, I had to narrow the include option to src/**/*.ts:

{
  "compilerOptions": {
    "target": "es2021",
    "module": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "noEmit": true,
    "skipLibCheck": true
  },
-  "include": ["**/*.ts"]
+  "include": ["src/**/*.ts"]
}

This change made tsc work.

The downside - now TypeScript config is applied only to src directory and files in test are excluded. VSCode could no longer resolve click on #utils.js import in the test directory, and vitest throws an error:

Error: Failed to load url #utils.js (resolved id: #utils.js) in /xxx/subpath-imports-typescript/test/index.spec.ts. Does the file exist?

The first potential solution was to point rootDir to "." instead of src to cover the entire project:

{
  "compilerOptions": {
    "target": "es2021",
    "module": "NodeNext",
-   "rootDir": "src",
+   "rootDir": ".",
    "outDir": "dist",
    "noEmit": true,
    "skipLibCheck": true
  },
-  "include": ["src/**/*.ts"]
+  "include": ["**/*.ts"]
}

However, that also didn’t help. When I ran tsc, TypeScript still complained:

Cannot find module '#utils.js' or its corresponding type declarations.

Now the reason was different. When rootDir was set to ".", TypeScript replicated whole project structure inside the dist directory, resulting in:

├── dist
│   ├── src
│   │   ├── index.js
│   │   └── utils.js
│   └── test
│       └── index.spec.js

But the imports field in package.json pointed to dist/utils.js, not dist/src/utils.js.

Attempt #4: Point to `dist/src`

Okey. I've adjusted the imports field to point to dist/src:

{
  "imports": {
-    "#*": "./dist/*"
+    "#*": "./dist/src/*"
  }
}

This change allowed tsc to work correctly, and VSCode could now navigate to utils.js in src.

However, when I tried to build the project with npm run build, I've got an error:

Cannot find module '#utils.js' or its corresponding type declarations.

The issue was that tsconfig.build.json still had rootDir pointed to src. I've updated rootDir to "." in tsconfig.build.ts as well:

// tsconfig.build.ts
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
-    "rootDir": "src",
+    "rootDir": ".",
    "outDir": "dist",
    "noEmit": false,
  },
  "include": ["src"]
}

Now, TypeScript is happy, and I could compile and build the project! 🎉
Yes, it introduced extra nesting inside the dist directory. Previously, the dist directory looked like this:

├── dist
│   ├── index.js
│   └── utils.js

And now with nested src:

├── dist
│   ├── src
│   │   ├── index.js
│   │   └── utils.js

Not a big deal, I'm ready to accept that!

But.. Tests still don't run 🤯

npm run test produces an error:

Failed to load url #utils.js (resolved id: #utils.js) in /xxx/subpath-imports-typescript/test/index.spec.ts. Does the file exist?

It's because only TypeScript is aware of the rootDir and outDir re-mapping. All other tools, like Vitest, didn’t recognize the mapping, leading to runtime errors when trying to resolve the #utils.js from the test directory.

I was stuck. I was going to give up on those mysterious subpath imports and return to TypeScript path aliases. But after reading more documentation and GitHub issues, I found a solution!

Attempt #5: Custom Conditions to the Rescue

According to Node.js docs, you can map single import alias to several locations via object:

"imports": {
  "#*": {
    "condition-a": "./location-a/*",
    "condition-b": "./location-b/*"
  }
}

Keys of that object are called conditions. There are built-in conditions like default, require or import, but also there can be any custom string, defined by user.

I've modified the imports field in package.json to include a custom condition my-package-dev pointing to src and kept default condition pointing to dist:

"imports": {
-  "#*": "./dist/src/*"
+  "#*": {
+    "my-package-dev": "./src/*",
+    "default": "./dist/*"
+  }
}

So, there are two ways for resolving # imports:

my-package-dev - tells Node.js to resolve paths from the src directory when condition is enabled (during development)
default - fallback option to resolve paths from the dist directory when no specific condition is provided

Note: I intentionally named my condition my-package-dev, not just dev. This is important for library authors. If your consumers run their project with dev condition, your package in node_modules will consider that condition as well and will try to resolve files from src! If you develop end users app, you can use dev or development as a condition name.

Update TypeScript Configuration

Now I need to let TypeScript know about my custom condition. Luckily, tsconfig.json provides a customConditions option for that. I've reverted all the changes made in the previous steps and added customConditions field:

// tsconfig.json
"compilerOptions": {
  "target": "es2021",
  "module": "NodeNext",
+  "customConditions": ["my-package-dev"],
  "noEmit": true,
  "skipLibCheck": true,
}

With this setup, TypeScript correctly resolves subpath imports from the src directory even without rootDir and outDir options. VSCode also correctly navigates to utils.ts location.

Update Vitest Configuration

Vitest also supports providing custom conditions. I've set resolve.conditions in vitest.config.mts:

import { defineConfig } from 'vitest/config';

export default defineConfig({
+  resolve: {
+    conditions: ['my-package-dev'],
+  },
});

After this change, vitest was resolving files from src directory ensuring I check actual code during tests:

Other Tools

For other tools, you should check their documentation on custom conditions support. I've tried to run my project with tsx. As it supports all Node.js flags, I've just provided custom condition via -C flag:

$ npx tsx -C my-package-dev src/index.ts
42

It works.

I can recommend a comprehensive overview of subpath imports support in different tools and IDEs.

Recap

It was a challenging journey to setup subpath imports. Especially when ensuring compatibility across the development flow, testing tools, IDE support and production run 😜

However, the result is successful, and the final setup is not something very complex. I'm confident, subpath imports will eventually become a default way for aliasing in JavaScrip / TypeScript projects. I hope this article saves you time!

I've published a final working example on GitHub, you are welcome to check it out. Thanks for reading and happy coding! ❤️

Returning JSX from React Server Actions

Vitaliy Potapov — Fri, 30 Aug 2024 16:09:31 +0000

Did you know that Next.js Server Actions can return React Components JSX instead of raw JSON data?

While it's not explicitly mentioned in the docs, I was pleasantly surprised that it works.

Example

I have a page that renders users list with server action:

export default function Page() {
  async function loadUsersAction() {
    "use server";

    return [
      { name: "John", age: 30 },
      { name: "Jane", age: 25 },
      { name: "Doe", age: 40 },
    ];
  }

  return <UsersList loadUsersAction={loadUsersAction} />;
}

UsersList component loads users by button click:

'use client';

import { useState } from 'react';

export default function UsersList({ loadUsersAction }) {
  const [users, setUsers] = useState();

  const onClick = async () => {
    const data = await loadUsersAction();
    setUsers(data);
  };

  return (
    <>
      <button onClick={onClick}>Load users</button>
      <ul>
        {users?.map((user) => (
          <li key={user.name}>
            {user.name} - {user.age}
          </li>
        ))}
      </ul>
    </>
  );
}

Demo:

Now I change server action to return JSX with rendered users:

async function loadUsersAction() {
  "use server";

  const users = [
    { name: "John", age: 30 },
    { name: "Jane", age: 25 },
    { name: "Doe", age: 40 },
  ];

  return (
    <ul>
      {users?.map((user) => (
        <li key={user.name}>
          {user.name} - {user.age}
        </li>
      ))}
    </ul>
  );
}

And in UsersList component just render server action response:

export default function UsersList({ loadUsersAction }) {
  const [users, setUsers] = useState();

  const onClick = async () => {
    const data = await loadUsersAction();
    setUsers(data);
  };

  return (
    <>
      <button onClick={onClick}>Load users</button>
      {users}
    </>
  );
}

In browser everything works in the same way!

Note on errors handling

What if server action throws an error? When it returns a JSON data, we can catch that error inside action and return it in own format like:

{ error: "my error" }

When returning JSX, we can let error throw and catch it on the client with the nearest error boundary. As server action is called not inside a <form> element, it should be wrapped into Transition for proper errors handling. For Next.js it means that the nearest error.tsx file will be displayed in case of error.

The final code of UsersList component:

'use client';

import { useState, useTransition } from 'react';

export default function UsersList({ loadUsersAction }) {
  const [isPending, startTransition] = useTransition();
  const [users, setUsers] = useState();

  const onClick = () => {
    startTransition(async () => {
      const data = await loadUsersAction();
      setUsers(data);
    });
  };

  return (
    <>
      <button onClick={onClick}>Load users</button>
      {isPending ? <div>Loading users...</div> : users}
    </>
  );
}

Additionally, I utilize isPending flag to show message while loading users.

Demo:

You can check out a fully working example on GitHub.
Thanks for reading and happy coding! ❤️

DEV Community: Vitaliy Potapov

Turbopack: A Better Way to Inline SVG in Next.js 16

Why Existing Approaches Fall Short

1. Next <Image />

2. SVGR (@svgr/webpack)

3. SVG Sprite Maps

a) Pre-build script

b) Loader-based sprite generation

Solution: Inline Small SVGs as Data URI

Building a Custom Turbopack SVG Loader

Problem 1: Conditional Inlining

Problem 2: Customizing Icon Color

Packaging the Loader

Conclusion

Authentication in Playwright: You Might Not Need Project Dependencies

The usual way: a “setup” project

The big drawback: setup runs even when not needed

A simpler idea

Code: multi-role auth on demand (no setup project)

tests/admin.spec.ts

tests/user.spec.ts

Running the tests

1) Run everything (user + admin)

2) Run only "user" tests

3) Run only "admin" tests

4) Run on two shards (split by files)

Bonus: persistent auth for local dev

How to enable Global Cache

Notes

Side-by-side: dependency project vs Global Cache

Wrap-up

Global Cache: Make Playwright BeforeAll Run Once for All Workers

Intro

The "Test Setup" Parallelization Problem

Example

1. Project dependency

2. Global setup

3. BeforeAll

A "Global Cache" Solution

You might not need BeforeAll

Multiple files with conditional auth

Recap

Fix the Most Annoying MS Teams Bug: Reveal Hidden Tabs While Presenting

🤯 The Problem: Teams Toolbar Hides Your Tabs

🤔 Why Existing Workarounds Don’t Cut It

🛠️ My Simple Fix: A Tiny Chrome Extension

🔗 Try It Out

Open bookmarks in a new tab by default — easier said than done

🧩 The Problem: Why Isn’t This a Built-In Feature?

🔍 First Attempt: Capture Bookmark Navigation

💡 The Breakthrough: Downloads Instead of Navigation

🕸️ Attempted Tricks: Redirects, Fragments, and More

❌ Fragments Don’t Work

❌ Custom Hostnames? Nope.

🧙 The Hack That Worked: Username in URL

🏗️ Final Architecture

💤 The Wakeup Problem

⚠️ Known Limitations

🎉 Conclusion

[Boost]

Request-Mocking-Protocol: A New Approach to Mocking Server-Side Requests in E2E Testing

Vitaliy Potapov ・ Mar 13

Request-Mocking-Protocol: A New Approach to Mocking Server-Side Requests in E2E Testing

The Problem: Testing Server-Side Data Fetching

Existing Approaches

Playwright Proxy Approach

Mock Service Worker (MSW)

Proposed Solution

How It Works

Implementation

Define Schemas

Playwright Integration

Handling on the Server

Read Incoming Headers and Extract Schemas

Intercept Outgoing Requests

Testing the Whole Flow

Wrapping into a Library

Example Usage with the Library

Recap

"Fix with AI" Button in Playwright HTML Report

1. Next `<Image />`

2. SVGR (`@svgr/webpack`)

`tests/admin.spec.ts`

`tests/user.spec.ts`

Check 1: Changing the Role from `link` to `button`

What Does the `gitCommitInfo` Plugin Do?

Enter `playwright-network-cache`

Attempt #2: Use `dist` instead of `src`

Attempt #3: Set `rootDir` and `outDir`

Attempt #4: Point to `dist/src`