DEV Community: Gustavo Meilus

Smart Test Skipping: Building a Lightweight Playwright Dependency Analyzer

Gustavo Meilus — Thu, 30 Oct 2025 20:46:57 +0000

When an end-to-end test suite scales, so does the frustration from cascading failures. A single bug in a core component, like a LoginPage or HeaderPage, can cause dozens of dependent tests to fail, flooding your test report with noise. This makes it difficult to pinpoint the root cause.

A common solution is test dependency analysis: if a test for LoginPage fails, automatically skip all other tests that use LoginPage.

In this article, you'll build a simple, lightweight dependency analyzer that uses your Page Objects to provide smart "skip-if-failed" logic with minimal setup.

What We'll Build

An Analyzer: A single utility file that reads a test file and extracts its Page Object dependencies. It does this by looking at direct imports and new SomePage(...) instantiations.
A Fixture Integration: A simple override for the Playwright context fixture that:
- Analyzes the test file before it runs.
- Skips the test if any of its Page Object dependencies failed in a previous run.
- Records the test's dependencies to a JSON file if it fails.

Let's get started.

Step 1: Create the Dependency Analyzer

First, we'll create the core logic in playwright/utils/testDependencyAnalyzer.ts. This file will contain all the functions needed to parse, record, and check for failures. We'll build it piece by piece.

Defining the Failure Record

To start, let's define the shape of the data we'll save to our JSON cache file. This type, FailureRecord, will store information about a failed test and its dependencies.

import * as fs from 'fs';
import * as fsp from 'fs/promises';
import * as path from 'path';

type FailureRecord = {
  testFile: string;
  testTitle: string;
  timestamp: string;
  errorFiles: string[]; // Files found in the error stack
  dependencies: string[]; // Page Objects this test uses
  testId: string;
  skipped?: boolean;
};

The Main Analyzer Function

This is the main function, analyzePageDependencies. It reads a test file, finds the project root, and then uses two methods to build a unique set of Page Object dependencies.

/**
 * Analyze a test file for Page Object dependencies.
 */
export function analyzePageDependencies(testFilePath: string): string[] {
  const content = fs.readFileSync(testFilePath, 'utf-8');
  const projectRoot = findProjectRoot(testFilePath); // Helper we'll define later
  const deps = new Set<string>();

  // 1. Find direct imports
  for (const p of extractDirectImports(content)) {
    const resolved = resolveImportPath(projectRoot, testFilePath, p);
    if (resolved && isPageObjectPath(resolved)) deps.add(resolved);
  }

  // 2. Find 'new PageObject()' instantiations
  for (const cls of extractPageClassInstantiations(content)) {
    const file = findPageObjectFileByClass(projectRoot, cls);
    if (file) deps.add(toRelative(projectRoot, file));
  }

  return Array.from(deps).sort();
}

Analysis Helpers: Parsing the Code

The main function relies on several helper functions to do the actual parsing.

1. Extracting Imports: We use regex to find all import statements and return the path.

/**
 * HELPER: Extract import sources.
 */
function extractDirectImports(content: string): string[] {
  const imports: string[] = [];
  const patterns = [
    /import\s+(?:{[^}]+}|[\w*]+)\s+from\s+['"]([^'\"]+)['"]/g,
    /import\s+['"]([^'\"]+)['"]/g,
    /import\s+\*\s+as\s+\w+\s+from\s+['"]([^'\"]+)['"]/g,
  ];
  for (const re of patterns) {
    let m;
    while ((m = re.exec(content)) !== null) imports.push(m[1]);
  }
  return imports;
}

2. Extracting Class Instantiations: We use another regex to find code like new SomePage(...). This is crucial for tests that might not import the page directly (e.g., if it comes from another helper).

/**
 * HELPER: Extract class names of `new SomePage(...)`.
 */
function extractPageClassInstantiations(content: string): string[] {
  const classes: string[] = [];
  // Look for 'new' followed by a class name ending in 'Page'
  const re = /new\s+(\w+Page)\s*\(/g;
  let m;
  while ((m = re.exec(content)) !== null) classes.push(m[1]);
  return Array.from(new Set(classes));
}

3. Identifying Page Objects: These helpers determine if a file path is a Page Object and find its file location by its class name. This is based on the convention that Page Objects live in playwright/pages or playwright/_redesign/pages.

/**
 * HELPER: Identify Page Object files by convention.
 */
function isPageObjectPath(relPath: string): boolean {
  return (
    relPath.includes('playwright/_redesign/pages') ||
    relPath.includes('playwright/pages') ||
    relPath.endsWith('.page.ts') ||
    relPath.endsWith('.page.tsx')
  );
}

/**
 * HELPER: Find a Page Object file by exported class name.
 */
function findPageObjectFileByClass(
  projectRoot: string,
  className: string,
): string | null {
  const dirs = [
    path.join(projectRoot, 'playwright/_redesign/pages'),
    path.join(projectRoot, 'playwright/pages'),
  ];
  for (const dir of dirs) {
    if (!fs.existsSync(dir)) continue;
    const files = getAllFiles(dir); // getAllFiles is a recursive file reader
    for (const f of files) {
      if (!/\.tsx?$/.test(f)) continue;
      const content = fs.readFileSync(f, 'utf-8');
      if (content.includes(`export class ${className}`)) return f;
    }
  }
  return null;
}

(Note: We'll include the other helpers like findProjectRoot, resolveImportPath, getAllFiles, and toRelative in the final code block. They are standard file/path utilities.)

Checking for Failures

This function, hasFailedPageDependencies, is used by our fixture before a test runs. It reads the failure cache and checks if any of the test's dependencies are on the list of previously failed files.

/**
 * Return true if any previously failed dependency matches current Page Object deps.
 */
export async function hasFailedPageDependencies(
  dependencies: string[],
): Promise<boolean> {
  if (!dependencies.length) return false;
  const failures = await readDependencyFailures(); // Helper to read JSON cache
  if (!failures.length) return false;

  return failures.some(
    (f) =>
      // Check if any error file matches a dependency
      f.errorFiles?.some((err) => matchesDependency(err, dependencies)) ||
      // Fallback: check error text
      errorTextContainsDependency(
        [(f as any)?.error?.message ?? '', (f as any)?.error?.stack ?? '']
          .join(' ')
          .toLowerCase(),
        dependencies,
      ),
  );
}

Recording Failures

This function, recordPageDependencyFailure, is used by our fixture after a test fails. It collects all file paths from the test's error stack and saves a new FailureRecord to our JSON cache.

/**
 * Record dependency failure for a test on failure/timeout.
 */
export async function recordPageDependencyFailure(
  testInfo: any,
  dependencies: string[],
): Promise<void> {
  if (!testInfo || !dependencies.length) return;

  // Find all file paths in the error stack
  const errorFiles = collectErrorFiles(testInfo);
  if (errorFiles.length === 0) return;

  const testId = testInfo.testId || 'unknown';
  const failures = await readDependencyFailures();

  // Don't record the same failure twice
  if (failures.find((x) => x?.testId === testId)) return;

  const record: FailureRecord = {
    testFile: testInfo.file || 'unknown',
    testTitle: testInfo.title || 'unknown',
    timestamp: new Date().toISOString(),
    errorFiles,
    dependencies,
    testId,
  };

  failures.push(record);
  await writeDependencyFailures(failures); // Helper to write to JSON cache

  if (Array.isArray(testInfo.annotations)) {
    testInfo.annotations.push({
      type: 'dependency-failure',
      description: "'Recorded Page Object dependency failure',"
    });
  }
}

Cache and Error Helpers

Finally, we need functions to read/write the cache file (tmp/dependency-failures.json) and to parse error stacks. The deletePageDependencyFailures function is exported so our globalSetup can clear the cache.

/**
 * Support util: delete the failures file.
 */
export async function deletePageDependencyFailures(): Promise<void> {
  const p = getFailuresPath();
  await fsp.unlink(p).catch(() => {}); // Ignore if file doesn't exist
}

/**
 * Persist/Load failures.
 */
function getFailuresPath(): string {
  const tmpDir = path.join(process.cwd(), 'tmp');
  return path.join(tmpDir, 'dependency-failures.json');
}

async function readDependencyFailures(): Promise<FailureRecord[]> {
  try {
    const p = getFailuresPath();
    const txt = await fsp.readFile(p, 'utf-8').catch(() => '[]');
    if (!txt.trim()) return [];
    const j = JSON.parse(txt);
    return Array.isArray(j) ? j : [];
  } catch {
    return [];
  }
}

async function writeDependencyFailures(
  failures: FailureRecord[],
): Promise<void> {
  const tmpDir = path.join(process.cwd(), 'tmp');
  await fsp.mkdir(tmpDir, { recursive: true });
  const p = getFailuresPath();
  await fsp.writeFile(p, JSON.stringify(failures, null, 2));
}

/**
 * Error helpers.
 */
function collectErrorFiles(testInfo: any): string[] {
  // ... (logic to parse testInfo.error, testInfo.result.error, etc.)
  // This function is complex and included in the full code block below
  // ...
  return []; // Placeholder for snippet
}

Complete Analyzer Code

Here is the complete code for playwright/utils/testDependencyAnalyzer.ts. This includes all the helper functions (like findProjectRoot, getAllFiles, collectErrorFiles, etc.) that were abbreviated in the snippets above.

/**
 * A dependency analyzer for Playwright tests based on Page Objects.
 * - Extracts dependencies from:
 * 1) Direct imports
 * 2) `new SomePage(...)` class instantiations resolved by scanning pages dirs
 */

import * as fs from 'fs';
import * as fsp from 'fs/promises';
import * as path from 'path';

type FailureRecord = {
  testFile: string;
  testTitle: string;
  timestamp: string;
  errorFiles: string[];
  dependencies: string[];
  testId: string;
  skipped?: boolean;
};

/**
 * Analyze a test file for Page Object dependencies.
 */
export function analyzePageDependencies(testFilePath: string): string[] {
  const content = fs.readFileSync(testFilePath, 'utf-8');
  const projectRoot = findProjectRoot(testFilePath);
  const deps = new Set<string>();

  for (const p of extractDirectImports(content)) {
    const resolved = resolveImportPath(projectRoot, testFilePath, p);
    if (resolved && isPageObjectPath(resolved)) deps.add(resolved);
  }

  for (const cls of extractPageClassInstantiations(content)) {
    const file = findPageObjectFileByClass(projectRoot, cls);
    if (file) deps.add(toRelative(projectRoot, file));
  }

  return Array.from(deps).sort();
}

/**
 * Return true if any previously failed dependency matches current Page Object deps.
 */
export async function hasFailedPageDependencies(
  dependencies: string[],
): Promise<boolean> {
  if (!dependencies.length) return false;
  const failures = await readDependencyFailures();
  if (!failures.length) return false;

  return failures.some(
    (f) =>
      f.errorFiles?.some((err) => matchesDependency(err, dependencies)) ||
      errorTextContainsDependency(
        [(f as any)?.error?.message ?? '', (f as any)?.error?.stack ?? '']
          .join(' ')
          .toLowerCase(),
        dependencies,
      ),
  );
}

/**
 * Record dependency failure for a test on failure/timeout.
 */
export async function recordPageDependencyFailure(
  testInfo: any,
  dependencies: string[],
): Promise<void> {
  if (!testInfo || !dependencies.length) return;

  const errorFiles = collectErrorFiles(testInfo);
  if (errorFiles.length === 0) return;

  const testId = testInfo.testId || 'unknown';
  const failures = await readDependencyFailures();
  if (failures.find((x) => x?.testId === testId)) return;

  const record: FailureRecord = {
    testFile: testInfo.file || 'unknown',
    testTitle: testInfo.title || 'unknown',
    timestamp: new Date().toISOString(),
    errorFiles,
    dependencies,
    testId,
  };

  failures.push(record);
  await writeDependencyFailures(failures);

  if (Array.isArray(testInfo.annotations)) {
    testInfo.annotations.push({
      type: 'dependency-failure',
      description: "'Recorded Page Object dependency failure',"
    });
  }
}

/**
 * Support util: delete the failures file.
 */
export async function deletePageDependencyFailures(): Promise<void> {
  const p = getFailuresPath();
  await fsp.unlink(p).catch(() => {});
}

/**
 * HELPER: Extract import sources.
 */
function extractDirectImports(content: string): string[] {
  const imports: string[] = [];
  const patterns = [
    /import\s+(?:{[^}]+}|[\w*]+)\s+from\s+['"]([^'\"]+)['"]/g,
    /import\s+['"]([^'\"]+)['"]/g,
    /import\s+\*\s+as\s+\w+\s+from\s+['"]([^'\"]+)['"]/g,
  ];
  for (const re of patterns) {
    let m;
    while ((m = re.exec(content)) !== null) imports.push(m[1]);
  }
  return imports;
}

/**
 * HELPER: Extract class names of `new SomePage(...)`.
 */
function extractPageClassInstantiations(content: string): string[] {
  const classes: string[] = [];
  const re = /new\s+(\w+Page)\s*\(/g;
  let m;
  while ((m = re.exec(content)) !== null) classes.push(m[1]);
  return Array.from(new Set(classes));
}

/**
 * HELPER: Resolve import path relative to the test file and project root.
 */
function resolveImportPath(
  projectRoot: string,
  testFilePath: string,
  importPath: string,
): string | null {
  if (!importPath.startsWith('.') && !importPath.startsWith('/')) return null;
  const testDir = path.dirname(testFilePath);
  const abs = path.resolve(testDir, importPath);

  if (fs.existsSync(abs)) return toRelative(projectRoot, abs);

  const exts = ['.ts', '.tsx', '.js', '.jsx'];
  for (const ext of exts) {
    if (fs.existsSync(abs + ext)) return toRelative(projectRoot, abs + ext);
  }

  const idxs = ['index.ts', 'index.tsx', 'index.js'];
  for (const idx of idxs) {
    const p = path.join(abs, idx);
    if (fs.existsSync(p)) return toRelative(projectRoot, p);
  }

  return null;
}

/**
 * HELPER: Identify Page Object files by convention.
 */
function isPageObjectPath(relPath: string): boolean {
  return (
    relPath.includes('playwright/_redesign/pages') ||
    relPath.includes('playwright/pages') ||
    relPath.endsWith('.page.ts') ||
    relPath.endsWith('.page.tsx')
  );
}

/**
 * HELPER: Find a Page Object file by exported class name.
 */
function findPageObjectFileByClass(
  projectRoot: string,
  className: string,
): string | null {
  const dirs = [
    path.join(projectRoot, 'playwright/_redesign/pages'),
    path.join(projectRoot, 'playwright/pages'),
  ];
  for (const dir of dirs) {
    if (!fs.existsSync(dir)) continue;
    const files = getAllFiles(dir);
    for (const f of files) {
      if (!/\.tsx?$/.test(f)) continue;
      const content = fs.readFileSync(f, 'utf-8');
      if (content.includes(`export class ${className}`)) return f;
    }
  }
  return null;
}

/**
 * HELPER: Recursively list files.
 */
function getAllFiles(dir: string): string[] {
  if (!fs.existsSync(dir)) return [];
  const out: string[] = [];
  for (const entry of fs.readdirSync(dir)) {
    const p = path.join(dir, entry);
    const st = fs.statSync(p);
    if (st.isDirectory()) out.push(...getAllFiles(p));
    else out.push(p);
  }
  return out;
}

/**
 * HELPER: Project root discovery.
 */
function findProjectRoot(startPath: string): string {
  let cur = path.resolve(startPath);
  while (cur !== path.dirname(cur)) {
    const pkg = path.join(cur, 'package.json');
    if (fs.existsSync(pkg)) return cur;
    cur = path.dirname(cur);
  }
  return cur;
}

/**
 * HELPER: Normalize to project-relative unix path.
 */
function toRelative(root: string, abs: string): string {
  return path.relative(root, abs).replace(/\\/g, '/');
}

/**
 * Persist/Load failures.
 */
function getFailuresPath(): string {
  const tmpDir = path.join(process.cwd(), 'tmp');
  return path.join(tmpDir, 'dependency-failures.json');
}

async function readDependencyFailures(): Promise<FailureRecord[]> {
  try {
    const p = getFailuresPath();
    const txt = await fsp.readFile(p, 'utf-8').catch(() => '[]');
    if (!txt.trim()) return [];
    const j = JSON.parse(txt);
    return Array.isArray(j) ? j : [];
  } catch {
    return [];
  }
}

async function writeDependencyFailures(
  failures: FailureRecord[],
): Promise<void> {
  const tmpDir = path.join(process.cwd(), 'tmp');
  await fsp.mkdir(tmpDir, { recursive: true });
  const p = getFailuresPath();
  await fsp.writeFile(p, JSON.stringify(failures, null, 2));
}

/**
 * Error helpers.
 */
function collectErrorFiles(testInfo: any): string[] {
  const set = new Set<string>();
  const addFrom = (stack?: string) => {
    if (!stack) return;
    const re = /at\s+.*?\((.+?):\d+:\d+\)|at\s+(.+?):\d+:\d+/g;
    let m;
    const root = process.cwd();
    while ((m = re.exec(stack)) !== null) {
      const file = (m[1] || m[2])?.replace(/\\/g, '/');
      if (!file) continue;
      if (file.includes('node_modules')) continue;
      const abs = path.isAbsolute(file)
        ? file
        : path.resolve(root, file).replace(/\\/g, '/');
      set.add(abs);
    }
  };

  const stepMap = (testInfo as any)?._stepMap;
  if (stepMap) {
    for (const [, step] of stepMap.entries()) {
      if (step?.error && step?.location?.file) set.add(step.location.file);
      if (step?.error?.stack) addFrom(step.error.stack);
    }
  }
  if (testInfo.error?.location?.file) set.add(testInfo.error.location.file);
  if (testInfo.error?.stack) addFrom(testInfo.error.stack);
  if (testInfo.result?.error?.location?.file)
    set.add(testInfo.result.error.location.file);
  if (testInfo.result?.error?.stack) addFrom(testInfo.result.error.stack);
  for (const err of testInfo.errors || []) {
    if (err?.location?.file) set.add(err.location.file);
    if (err?.stack) addFrom(err.stack);
  }
  return Array.from(set);
}

function errorTextContainsDependency(
  lowerText: string,
  dependencies: string[],
): boolean {
  return dependencies.some((dep) => {
    const base = dep.split('/').pop() || dep;
    const parts = dep.split('/').filter(Boolean);
    const lowerDep = dep.toLowerCase();
    return (
      lowerText.includes(base.toLowerCase()) ||
      lowerText.includes(lowerDep) ||
      parts.some((p) => lowerText.includes(p.toLowerCase()))
    );
  });
}

function matchesDependency(errorFile: string, dependencies: string[]): boolean {
  if (!errorFile) return false;
  const normalized = errorFile.replace(/^.*monument-core\//, '');
  const base = normalized.split('/').pop() || '';
  return dependencies.some((dep) => {
    const depBase = dep.split('/').pop() || dep;
    return (
      normalized.includes(dep) ||
      errorFile.includes(dep) ||
      depBase === base ||
      normalized.endsWith(dep)
    );
  });
}

Step 2: Wire the Analyzer into a Fixture

Now we'll use this analyzer in our Playwright setup. The best place is by extending the context fixture, as it runs before each test. We'll import the functions we just built and inject the logic.

Create a new fixture file (or add to your existing one):

import { test as base } from '@playwright/test';
import {
  analyzePageDependencies,
  hasFailedPageDependencies,
  recordPageDependencyFailure,
} from './testDependencyAnalyzer'; // Adjust the import path

export const test = base.extend({
  // We override the 'context' fixture.
  context: async ({ browser, baseURL }, use) => {
    // 1. Get info for the test that is about to run
    const testInfo = base.info();

    // 2. ANALYZE: Get Page Object dependencies for the current test file
    const deps = analyzePageDependencies(testInfo.file);

    // 3. CHECK & SKIP: Check if any of those dependencies have failed before
    if (await hasFailedPageDependencies(deps)) {
      // If yes, skip this test immediately
      test.skip(
        true,
        'Skipping due to previous Page Object dependency failures',
      );
    }

    // --- Standard fixture setup ---
    const context = await browser.newContext({
      baseURL,
      ignoreHTTPSErrors: true,
    });
    // --- End standard setup ---

    try {
      // 4. RUN: Run the test
      await use(context);
    } finally {
      // 5. RECORD: This block runs after the test is finished
      await context.close();

      // If the test failed or timed out, record its dependencies as failed
      if (testInfo.status === 'failed' || testInfo.status === 'timedOut') {
        await recordPageDependencyFailure(testInfo, deps);
      }
    }
  },
});

// Re-export 'expect' so users can import { test, expect } from this file
export { expect } from '@playwright/test';

How It Works: The Fixture Logic

Get Test Info: We get the test's file path from testInfo.file.
Analyze: We pass this path to our new analyzePageDependencies function.
Check & Skip: We pass the resulting dependencies to hasFailedPageDependencies. If it returns true, we call test.skip() and the test is never executed.
Run: If it returns false, the test runs as normal using await use(context).
Record: In the finally block, we check testInfo.status. If the test failed, we call recordPageDependencyFailure to log the failure, which will cause dependent tests to be skipped in the next run.

Step 3: Usage in Tests

This is the best part. You don't need to change your tests at all.

The only change is the import. Instead of importing test from @playwright/test, you import it from your new fixture file.

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

After:
import { test, expect } from './my-fixtures.ts'; // (or wherever you saved your new fixture)

The fixture handles all the analysis and skip logic automatically.

Step 4: Clearing the Failure Cache

The tmp/dependency-failures.json file will persist between runs. This is intentional.

However, you'll want to clear it before starting a fresh CI run. You can use the deletePageDependencyFailures helper we built.

The easiest way is to add a globalSetup to your playwright.config.ts:

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { deletePageDependencyFailures } from './playwright/utils/testDependencyAnalyzer';

export default defineConfig({
  // ...
  globalSetup: async () => {
    // Clear the dependency failure cache before a full run
    await deletePageDependencyFailures();
  },
  // ...
});

Conclusion

You now have a powerful, lightweight test dependency system. It's built to analyze your Page Object dependencies to create a smart, self-healing test execution flow.

This approach gives you smarter test execution and cleaner failure reports by skipping tests that are destined to fail, all while remaining simple and decoupled from your test logic.

Scaling Your Playwright Tests: A Fixture for Multi-User, Multi-Context Worlds

Gustavo Meilus — Fri, 17 Oct 2025 20:19:50 +0000

Working on a large-scale, multi-tenant SaaS platform presents unique challenges for UI and API test automation. Our application has different user roles (admin, view-only, limited-access), and we need to validate features from the perspective of each.

The Problem

The traditional approach of logging in a specific user in a beforeEach hook for every single test is a notorious bottleneck. It's slow, adding seconds or even minutes to every test file. It's flaky, as login flows can be complex and prone to intermittent failures. And it's repetitive, violating the D.R.Y. (Don't Repeat Yourself) principle.

When you're running thousands of tests in parallel, this waste adds up, turning a 10-minute CI run into a 30-minute one.

The Goal

Our objective was to create a robust, scalable fixture system in Playwright that could:

Isolate Users Per Worker: Each parallel worker should manage its own set of users to avoid collisions.
Select User by Tag: Automatically pick the correct user (e.g., @admin, @viewOnly) based on the test's tags.
Log In Once: Perform the expensive login and user-creation logic once per user, not once per test.
Reuse Auth State: Save the authenticated storage state and reuse it.
Provide Test-Level Isolation: Ensure every single test runs in a pristine, isolated context to prevent state-bleeding between tests.
Manage Both UI and API: Provide both a BrowserContext (for UI tests) and an APIRequestContext (for API calls) for the selected user.

The Implementation (Worker Fixture: usersContext)

The heart of our solution is a worker-scoped fixture named usersContext. This fixture is initialized once for each parallel worker.

A previous version of this fixture created a single BrowserContext and APIRequestContext that were shared by all tests running on that worker. This was fast, but it had a major flaw: tests were not isolated. A popup left open in one test could cause the next test to fail.

Our new implementation solves this by making the usersContext a manager for test-scoped contexts. It's responsible for creating and destroying contexts on behalf of individual tests, ensuring 100% isolation.

The new secret sauce is a helper function called createLazyContext.

The createLazyContext Helper

This helper is a factory that produces context managers. It uses Map objects to track context instances and, critically, reference counts based on Playwright's testInfo.testId.

Here is a simplified view of its logic:

const createLazyContext = <T>(
  factory: () => Promise<T>, // The function that creates the context
  cleanup: (instance: T) => Promise<void> | void, // The function that destroys it
) => {
  const instances = new Map<string, T>();
  const initPromises = new Map<string, Promise<T>>();
  const referenceCounts = new Map<string, number>();

  return {
    init: async (testId: string) => {
      // If it already exists for this test, increment ref count
      const existingInstance = instances.get(testId);
      if (existingInstance) {
        referenceCounts.set(testId, (referenceCounts.get(testId) || 0) + 1);
        return existingInstance;
      }

      // ... (handles promises to prevent race conditions) ...

      // If it's new, run the (expensive) factory
      const instance = await factory();
      instances.set(testId, instance);
      referenceCounts.set(testId, 1); // Set initial ref count
      return instance;
    },

    cleanup: async (testId: string) => {
      const instance = instances.get(testId);
      if (!instance) return; // Nothing to clean

      const refCount = referenceCounts.get(testId) || 0;
      if (refCount > 1) {
        // If other fixtures still use this, just decrement the count
        referenceCounts.set(testId, refCount - 1);
        return;
      }

      // If ref count is 1, this is the last user.
      // Time to do the *real* cleanup.
      await cleanup(instance);
      instances.delete(testId);
      referenceCounts.delete(testId);
      initPromises.delete(testId);
    },
  };
};

The getOrCreateUser Function

The factory function passed to createLazyContext is our getOrCreateUser logic. This function is now far more robust:

It checks if a valid auth file (.auth/...json) already exists.
If not, it uses a master admin API context to:
- Check if the test user exists in the application's backend.
- If not, it programmatically creates the user and their required role via the API.
- It fetches the user's temporary password (in our case, from email).
- It performs an API login and password reset if needed.
Only after the user is guaranteed to exist and be in a valid state does it perform a final UI login. This is exclusively to save the storageState to disk for future use.

Using createLazyContext in the Worker

Our usersContext fixture now uses this helper to create managers for each context type. The worker itself no longer holds the contexts—it just holds the managers.

usersContext: [
  async ({ uiBaseURL, apiBaseURL, browser }, use) => {
    // ... (user definitions, selectUserByTags, getOrCreateUser) ...

    // Create a manager for the BrowserContext
    const browserContext = createLazyContext(
      async () => {
        const selectedUser = selectUserByTags(testInfo.tags, users);
        const userContext = await getOrCreateUser(selectedUser, ...);
        return userContext.userAccountContext;
      },
      async (context) => {
        await context.close(); // The *real* cleanup
      },
    );

    // Create a separate manager for the APIRequestContext
    const apiRequest = createLazyContext(
      async () => {
        const selectedUser = selectUserByTags(testInfo.tags, users);
        const userContext = await getOrCreateUser(selectedUser, ...);
        return userContext.userAccountRequestContext;
      },
      async (context) => {
        await context.dispose(); // The *real* cleanup
      },
    );

    // The worker fixture provides an object with init/cleanup methods
    const lazyUsersContext = {
      initializeBrowserContext: () => {
        const currentTestId = test.info().testId;
        return browserContext.init(currentTestId);
      },
      cleanupBrowserContext: (testId: string) =>
        browserContext.cleanup(testId),

      initializeApiRequest: () => {
        const currentTestId = test.info().testId;
        return apiRequest.init(currentTestId);
      },
      cleanupApiRequest: (testId: string) => 
        apiRequest.cleanup(testId),
      // ... (other helpers) ...
    };

    await use(lazyUsersContext);
  },
  { scope: 'worker' },
],

Tying it All Together: The Test-Scoped Fixtures

Now, our test-scoped fixtures (the ones our tests actually use) are responsible for triggering the creation and cleanup of their own contexts.

This is the most important change. The test fixtures now tell the worker manager when to start and stop.

export const test = base.extend<Fixtures, WorkerFixtures>({
  // ... (worker fixtures) ...

  // UI Context Fixture (for UI tests)
  context: async ({ usersContext }, use) => {
    const testInfo = test.info();

    // 1. TELL THE WORKER TO INIT A CONTEXT FOR THIS TEST
    const context = await usersContext.initializeBrowserContext();

    try {
      await use(context); // Run the test
    } finally {
      // 2. TELL THE WORKER TO CLEAN UP THE CONTEXT FOR THIS TEST
      await usersContext.cleanupBrowserContext(testInfo.testId);
    }
  },

  // API Request Fixture (for API tests)
  apiRequest: async ({ usersContext }, use) => {
    const testInfo = test.info();

    // 1. TELL THE WORKER TO INIT A CONTEXT FOR THIS TEST
    const apiRequest = await usersContext.initializeApiRequest();

    try {
      await use(apiRequest); // Run the test
    } finally {
      // 2. TELL THE WORKER TO CLEAN UP THE CONTEXT FOR THIS TEST
      await usersContext.cleanupApiRequest(testInfo.testId);
    }
  },
});

The New Magic of Per-Test Cleanup

This new structure gives us the best of all worlds. Let's trace the lifecycle for a single test:

A test test('my ui test', async ({ app }) => { ... }) starts.
Playwright sees app depends on context.
The context fixture runs. It calls usersContext.initializeBrowserContext().
Inside createLazyContext, it sees no instance for this testId. It runs the expensive getOrCreateUser factory.
A brand new BrowserContext is created. It's stored in the instances map, and its referenceCount is set to 1.
The app fixture runs, creates a new page, and the test body executes.
The test finishes.
The finally block in the context fixture runs. It calls usersContext.cleanupBrowserContext(testInfo.testId).
Inside createLazyContext, it finds the referenceCount is 1. It decrements it to 0.
Because the count is 0, it calls the real cleanup function: await context.close().
The BrowserContext is completely destroyed. The next test will start from a perfectly clean slate.

The reference counting is key. If another fixture also depended on initializeBrowserContext, it would just increment the count to 2. The real cleanup wouldn't happen until both fixtures had run their cleanup methods, bringing the count back to 0.

Conclusion

By moving context management from a "shared worker resource" to a "test-scoped resource managed by a worker," we've eliminated test-state pollution. This usersContext fixture now provides:

Maximum Performance: User creation and login logic is centralized and cached.
Maximum Isolation: Every test gets its own pristine BrowserContext and APIRequestContext.
Excellent Developer Experience: A test just needs to ask for app or api to get the right, pre-authenticated context for its tagged user role.

This pattern has been a game-changer for scaling our Playwright test suite, making it faster, more reliable, and much easier to maintain.

For further information, I highly recommend checking out the official Playwright documentation on Fixtures.

I hope you found this article helpful! If you have any questions or feedback, feel free to leave a comment.

Let's connect! You can follow my projects on GitHub or reach out on LinkedIn.

Connect on LinkedIn: https://www.linkedin.com/in/gmeilus

See me on GitHub: https://github.com/gustavo-meilus

Automation with Playwright: Building a Scalable Testing Architecture

Gustavo Meilus — Wed, 15 Oct 2025 14:52:01 +0000

In today's digital landscape, web applications must deliver flawless experiences across an expanding array of browsers, devices, and platforms. This increasing complexity creates significant challenges for testing teams who must ensure consistent functionality and user experience. Playwright has emerged as a powerful solution for testing in these complex scenarios, offering cross-browser compatibility and powerful automation capabilities that fits a wide range of solutions.

However, even with Playwright's robust feature set, many testing projects fail to achieve their full potential due to architectural shortcomings. Without a carefully designed structure, test suites quickly become unwieldy, difficult to maintain, and prone to failures that undermine their reliability. The true challenge lies not in individual test creation but in constructing a cohesive, maintainable testing ecosystem.

This comprehensive guide will transform your Playwright implementation from basic test scripts into a sophisticated framework that scales with your application. We'll focus on proven architectural patterns that promote code reusability, clear organization, and sustainable growth. By following these battle-tested approaches, you'll create a testing foundation that remains robust even as your application and team expand, ultimately improving both product quality and development velocity.

Setting Up Your Project Foundation

A well-structured Playwright project begins with thoughtful configuration. This section explores the essential elements that form the bedrock of a scalable testing architecture, focusing on settings that enhance test reliability, execution speed, and maintainability.

Optimizing Your Playwright Configuration

The playwright.config.ts file defines your testing framework's behavior. Key configuration options include:

Environment Management: Separate configuration from code for cleaner management.

import dotenv from 'dotenv';
import path from 'path';

// Read from ".env" file.
dotenv.config({ path: path.resolve(__dirname, '.env') });

Parallel Execution: Slash execution time for large test suites.

/* Run tests in files in parallel */
  fullyParallel: true,

Multi-Format Reporting: Get test results in formats suited to different needs.

/* Reporter to use. See https://playwright.dev/docs/test-reporters */
  reporter: [
    ['html'],
    ['list'],
    ['json', { outputFile: 'playwright-report/results.json' }]
  ],

Environment Portability: Use relative paths for cross-environment compatibility.

use: {
    /* Base URL to use in actions like `await page.goto('/')`. */
    baseURL: process.env.BASE_URL,

Authentication Management: Reuse authentication state across tests.

/* Configure projects */
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        /* Use prepared auth state. */
        storageState: '.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],

Here's the complete configuration:

// playwright.config.ts

import { defineConfig, devices } from '@playwright/test';
import dotenv from 'dotenv';
import path from 'path';

// Read from ".env" file.
dotenv.config({ path: path.resolve(__dirname, '.env') });

export default defineConfig({
  testDir: './tests',
  /* Run tests in files in parallel */
  fullyParallel: true,
  /* Fail the build on CI if you accidentally left test.only in the source code. */
  forbidOnly: !!process.env.CI,
  /* Retry on CI only */
  retries: process.env.CI ? 2 : 0,
  /* Opt out of parallel tests on CI. */
  workers: process.env.CI ? 1 : undefined,
  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
  reporter: [
    ['html'],
    ['list'],
    ['json', { outputFile: 'playwright-report/results.json' }]
  ],
  /* Shared settings for all the projects below. */
  use: {
    /* Base URL to use in actions like `await page.goto('/')`. */
    baseURL: process.env.BASE_URL,

    /* Collect trace when retrying the failed test. */
    trace: 'on-first-retry',
  },

  /* Configure projects */
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        /* Use prepared auth state. */
        storageState: '.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],
});

This configuration ensures test isolation, reproducibility, and clear reporting, establishing the foundation upon which the rest of your testing architecture will build. By taking time to configure these settings properly, you'll avoid common pitfalls that plague many testing projects and set your team up for long-term success.

Structuring Your Project Folders

As test suites grow, disorganized file structures quickly become unmanageable. This section introduces a domain-based organization pattern that scales naturally with your application, keeping related code together while maintaining clear boundaries between different functional areas.

Organizing for Clarity and Scale

A well-organized folder structure maintains clarity as your test suite grows. Consider this domain-based organization:

Structured layout of pages and tests for scalable automation.

This structure implements four key principles:

Domain-Driven Organization: Group related files by application domain for easy navigation
Test Type Separation: Divide tests by type (smoke, integration, end-to-end) for targeted execution
Component-Based Structure: Separate complex UI elements into discrete components for better reusability
Clear Separation of Concerns: Keep page objects, locators, and tests in separate files

This organization enables efficient test planning and execution based on domain and test type, while supporting the dynamic tagging system we'll explore later

The value of thoughtful file organization becomes increasingly apparent as your project grows. This structure not only makes it easier for team members to locate relevant files but also naturally enforces architectural boundaries that promote code quality. With domains clearly separated, changes to one area have minimal impact on others, reducing the risk of unintended side effects when making updates.

Creating Hierarchical Page Objects

The Page Object Model (POM) pattern is a cornerstone of maintainable test automation, but implementing it effectively for complex applications requires additional structure. This section introduces a hierarchical approach to page objects that balances flexibility with consistency through class inheritance and composition.

Separating Locators from Page Logic

Decouple UI element selectors from page behavior for cleaner, more maintainable code:

// login.locators.ts

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

export const onLoadLocators = (page: Page) => ({
  usernameTextbox: page.getByRole('textbox', { name: 'Username' }),
  passwordTextbox: page.getByRole('textbox', { name: 'Password' }),
  loginButton: page.getByRole('button', { name: 'Login' }),
  languagesButton: page.getByRole('button').filter({
    hasText: /^\$\/$/,
  }),
});

export const locators = (page: Page) => ({
  ...onLoadLocators(page),
  languageList: page.getByRole('list'),
});

Splitting locators into onLoadLocators and locators enables automatic loading verification during navigation.

This separation provides three key benefits:

Focused Responsibility: Locator files define selectors, page classes define behavior
Targeted Maintenance: Update locators in isolation when UI elements change
Enhanced Reusability: Share locators across different page objects as needed

Building the Page Object Foundation

Start with a clear interface that defines the contract for all page objects:

// IPageBase.ts

import { Locator, Page } from '@playwright/test';
import { IComponentBase } from '../common/base/component.base';

export interface IPageBase {
  readonly page: Page;
  readonly url: string;
  readonly onLoadLocators: Record<string, Locator>;
  readonly locators: Record<string, Locator>;

  waitLoadingLocators(timeout?: number): Promise<void>;

  goto(): Promise<void>;
  goto(checkVisibility: boolean): Promise<void>;
  goto(id: string, checkVisibility?: boolean): Promise<void>;
  goto(id: string, suffix: string, checkVisibility?: boolean): Promise<void>;
}

Then implement a base class that all page objects will extend:

// pages/base/page.base.ts (partial)

import { Locator, Page } from '@playwright/test';
import { IComponentBase } from '../common/base/component.base';

export abstract class PageBase implements IPageBase {
  abstract readonly page: Page;
  abstract readonly url: string;
  abstract readonly onLoudLocators: Record<string, Locator>;
  abstract readonly locators: Record<string, Locator>;
  private dynamicPath: string;

  constructor(page: Page) {
    this.page = page;
  }

  protected getComponents(): IComponentBase[] {
    return [];
  }

  protected mergeLocators(
    baseLocators: Record<string, Locator>,
  ): Record<string, Locator> {
    return this.getComponents().reduce(
      (acc, component) => ({ ...acc, ...component.locators }),
      baseLocators,
    );
  }

  protected mergeOnLoadLocators(
    baseLocators: Record<string, Locator>,
  ): Record<string, Locator> {
    return this.getComponents().reduce(
      (acc, component) => ({ ...acc, ...component.onLoadLocators }),
      baseLocators,
    );
  }

  // ... other methods like goto(), waitLoadingLocators() etc.
}

This base class provides:

Common navigation methods
Component integration
Loading verification
Dynamic URL support

Implementing Specific Page Objects

Page objects inherit from the base class and add domain-specific functionality:

// login.page.ts

export class LoginPage extends PageBase {
  readonly url = './login';
  readonly onLoadLocators: Record<string, Locator>;
  readonly locators: Record<string, Locator>;

  constructor(page: Page) {
    super(page);
    this.locators = locators(page);
    this.onLoadLocators = onLoadLocators(page);
  }

  async executeLogin(username: string, password: string) {
    await this.locators.usernameTextbox.fill(username);
    await this.locators.passwordTextbox.fill(password);
    await this.locators.loginButton.click();
  }
}

This creates a clean inheritance hierarchy where:

Base class provides common functionality
Specific page objects implement domain logic
Business-focused methods handle page interactions

By implementing this hierarchical POM approach, you create a flexible yet consistent foundation for all your page interactions. The separation of concerns makes each class more focused and easier to understand, while the inheritance structure eliminates duplication and enforces consistency. This approach scales naturally as your application grows, allowing you to model even the most complex interfaces with maintainable code.

Centralizing Page Management with Fixtures

Creating and managing page objects efficiently becomes challenging as test suites expand. This section introduces a centralized page management approach that simplifies test development through dependency injection, ensuring consistent object usage across your entire test suite.

The Page Manager Pattern

Create a factory function that centralizes page object instantiation:

// pages/index.ts

import { BrowserContext, Page } from '@playwright/test';
import { DashboardPage } from './dashboard/dashboard.page';
import { LoginPage } from './login/login.page';

export const pageManager = (page: Page, context: BrowserContext) => ({
  page,
  context,
  login: new LoginPage(page),
  dashboard: new DashboardPage(page),
});

This is the Dashboard page template

Test Fixtures for Dependency Injection

Use Playwright's test fixtures to inject the Page Manager into tests:

// fixtures.ts

import { test as base, Page } from '@playwright/test';
import { pageManager } from './pages';

type Fixtures = {
  app: ReturnType<typeof pageManager>;
};

export const test = base.extend<Fixtures>({
  app: async ({ page, context }, use) => {
    const manager = pageManager(page, context);
    await use(manager);
  },
});

export { expect } from '@playwright/test';


// This simplifies test code significantly:
/*

  // login.spec.ts
  test('check auth login', async ({ app }) => {
    await app.login.goto();
    await app.login.executeLogin(process.env.USER_NAME!, process.env.PASSWORD!);
    await app.page.waitForURL('./vue-element-admin/#/dashboard');
  });

This approach delivers four key benefits:

Streamlined Test Code: No manual page object creation needed
Consistent Object Usage: All tests use the same page object instances
Automatic Resource Management: Playwright handles context lifecycle
Type Safety: TypeScript ensures correct usage of page objects

Hierarchical page object structure for modular and reusable automation.

The page manager pattern is particularly valuable as your test suite grows and more developers join the project. By centralizing page object creation and providing a unified access point, you eliminate common errors and inconsistencies that arise when different tests instantiate objects differently. This centralized approach creates a more cohesive test suite with clearer patterns, making it easier for new team members to contribute effectively.

Implementing Dynamic Test Tagging

Test organization becomes crucial as your suite grows. This section introduces a powerful automated tagging system that derives test tags from your folder structure, enabling flexible test selection without requiring manual tag maintenance.

The Tags Function

Create a utility that extracts tags from file paths:

// fixtures.ts (getTags function)

export const getTags = (filePath: string) => {
  const tags: string[] = [];
  const normalizedPath = path.normalize(filePath);
  const parts = normalizedPath.split(path.sep);

  const pathParts = parts.filter((part) => part !== '');
  const folders = pathParts.slice(
    pathParts.indexOf('tests') + 1,
    pathParts.length - 1,
  );
  const fileName = pathParts[pathParts.length - 1];

  // Add tags from folder names
  if (folders) {
    folders.forEach((part) => {
      tags.push(`@${part}`);
    });
  }

  // Add tags from file name
  if (fileName) {
    const nameOnly = fileName
      .replace('.ts', '')
      .replace('.test', '')
      .replace('.setup', '')
      .replace('.spec', '');
    const parts = nameOnly.split('.');
    parts.forEach((part) => {
      tags.push(`@${part}`);
    });
  }

  // Return unique tags
  return [...new Set(tags)];
};

Applying Tags to Tests

Apply these tags to individual tests:

// tests/login/smoke/login.spec.ts

test(
  'check login screen loading',
  {
    tag: tags(__filename),
  },
  async ({ app }) => {
    await app.login.goto();
    const promises =
      Object.entries(app.login.onLoadLocators).map(
        (element) => {
          return expect(element[1]).toBeVisible();
        },
      );
    await Promise.all(promises);
  },
);

For a test file at tests/login/smoke/login.spec.ts, this generates tags like @login and @smoke. Run specific test subsets with:

npx playwright test --grep "@login"

Dynamic tagging provides four significant advantages:

Zero Manual Tagging: Tags generate automatically from your folder structure
Consistent Organization: Tags follow a predictable pattern
Flexible Test Selection: Run tests by domain, type, or other criteria
Self-Documenting Tests: File paths reveal test purpose and scope

The real power of this approach emerges when your test suite contains hundreds or thousands of tests. Dynamic tagging enables you to select precise subsets of tests based on any combination of criteria, facilitating focused testing during development and comprehensive testing in CI/CD pipelines. Because the tags are derived from your folder structure, they remain up-to-date without additional maintenance, creating a self-documenting system that evolves naturally with your project.

Managing Complex Pages with Component Objects

Modern web applications often contain intricate UI components that require dedicated abstractions. This section introduces a component-based architecture that breaks complex pages into manageable pieces, enabling reuse, parallel development, and simplified maintenance.

Component Base Structure

Define an interface and base class for all components:

// pages/common/base/component.base.ts

import { Locator, Page } from '@playwright/test';
import { PageBase } from '../../base/page.base';

export interface IComponentBase {
  readonly page: Page;
  readonly container: Locator;
  readonly onLoadLocators: Record<string, Locator>;
  readonly locators: Record<string, Locator>;

  waitLoadingLocators(timeout?: number): Promise<void>;
}

export abstract class ComponentBase extends PageBase implements IComponentBase {
  abstract readonly url: string;
  abstract readonly onLoadLocators: Record<string, Locator>;
  abstract readonly locators: Record<string, Locator>;
  abstract readonly container: Locator;

  constructor(page: Page) {
    super(page);
  }
}

This structure defines components with:

A reference to the page
A container element that scopes the component
Locators for UI elements
Loading verification methods

Implementing Components

Create individual component classes with their own locators:

// header-menu.component.ts

import { Locator, Page } from '@playwright/test';
import { ComponentBase } from '../base/component.base';
import { locators, onLoadLocators } from './header-menu.locators';

export class HeaderMenuPage extends ComponentBase {
  readonly url = './vue-element-admin/#';
  readonly onLoadLocators: Record<string, Locator>;
  readonly locators: Record<string, Locator>;
  readonly container: Locator;

  constructor(page: Page) {
    super(page);
    this.container = this.page.locator('.navbar');
    this.locators = locators(this.container);
    this.onLoadLocators = onLoadLocators(this.container);
  }
}

Component locators are scoped to their container:

// header-menu.locators.ts

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

export const onLoadLocators = (container: Locator) => ({
  hamburgerContainer: container.locator('#hamburger-container'),
  breadcrumbNav: container.getByLabel('Breadcrumb'),
  rightMenu: container.locator('.right-menu'),
  searchButton: container.locator('#header-search'),
  screenFullButton: container.locator('#screenfull'),
  sizeSelectButton: container.locator('#size-select'),
  languageButton: container.locator('.international'),
  accountButton: container.locator('.avatar-container'),
});

export const locators = (container: Locator) => ({
  ...onLoadLocators(container),
  accountDropdown: container.locator('#dropdown-menu-193'),
});

Common vs. Attached Components

Handle components in two ways:

Common Components (standalone in multiple pages):

Add them directly to the Page Manager:

// pages/index.ts

export const pageManager = (page: Page, context: BrowserContext) => ({
  page,
  context,
  login: new LoginPage(page),
  dashboard: new DashboardPage(page),
  leftMenu: new LeftMenuPage(page),
  headerMenu: new HeaderMenuPage(page),
});

Attached Components (belong to specific pages):

Create component hierarchies with base classes:

// pages/common/base/radar-chart.base.ts

export abstract class RadarChartBase implements IComponentBase {
  readonly page: Page;
  abstract readonly container: Locator;
  abstract readonly onLoadLocators: Record<string, Locator>;
  abstract readonly locators: Record<string, Locator>;

  constructor(page: Page) {
    this.page = page;
  }

  async waitLoadingLocators(timeout = 10000): Promise<void> {
    const promises =
      Object.keys(this.onLoadLocators).map((key) =>
        this.onLoadLocators[key].waitFor({ state: 'visible', timeout }),
      );
    await Promise.all(promises);
  }
}

This is the Radar Chart template on Dashboard page

Then implement specific components:

// pages/dashboard/budget-chart/budget-chart.component.ts

export class BudgetChartComponent extends RadarChartBase {
  readonly onLoadLocators: Record<string, Locator>;
  readonly locators: Record<string, Locator>;
  readonly container: Locator;

  constructor(page: Page) {
    super(page);
    this.container = page.getByRole('region', { name: 'Budget Chart' });
    this.locators = locators(this.container);
    this.onLoadLocators = onLoadLocators(this.container);
  }
}

Integrating Components with Pages

Compose complex pages from their components:

// pages/dashboard/dashboard.page.ts

export class DashboardPage extends PageBase {
  readonly url = './vue-element-admin/#/dashboard';
  readonly onLoadLocators: Record<string, Locator>;
  readonly locators: Record<string, Locator>;

  // Components
  readonly statsChart: StatsChartComponent;
  readonly budgetChart: BudgetChartComponent;
  // ... more components

  constructor(page: Page) {
    super(page);

    // Initialize components
    this.statsChart = new StatsChartComponent(page);
    this.budgetChart = new BudgetChartComponent(page);
    // ... initialize more components

    // Merge all locators
    this.locators = this.mergeLocators(locators(page));
    this.onLoadLocators = this.mergeOnLoadLocators(onLoadLocators(page));
  }

  protected getComponents(): IComponentBase[] {
    return [
      this.statsChart,
      this.budgetChart,
      // ... more components
    ];
  }
}

The PageBase class merges component locators automatically:

protected getComponents(): IComponentBase[] {
    return [];
  }

  protected mergeLocators(
    baseLocators: Record<string, Locator>,
  ): Record<string, Locator> {
    return this.getComponents().reduce(
      (acc, component) => ({ ...acc, ...component.locators }),
      baseLocators,
    );
  }

  protected mergeOnLoadLocators(
    baseLocators: Record<string, Locator>,
  ): Record<string, Locator> {
    return this.getComponents().reduce(
      (acc, component) => ({ ...acc, ...component.onLoadLocators }),
      baseLocators,
    );
  }

This component-based approach delivers four major benefits:

Focused Responsibility: Each component has a single clear purpose
Maximized Reusability: Components can be shared across pages
Parallel Development: Team members can work on different components simultaneously
Isolated Maintenance: Changes to components don't affect the rest of the page

Component-driven page object design with extended base functionality.

Component-based architecture truly shines when dealing with complex web applications. By modeling your application as a composition of discrete components, you create a more accurate representation that mirrors the application's actual structure. This approach not only makes tests more maintainable but also promotes better understanding of the application itself, bridging the gap between development and testing. The resulting test code becomes more intuitive, easier to debug, and significantly more adaptable to UI changes.

Conclusion

Building a sustainable testing architecture is an investment that pays dividends throughout your project's lifecycle. The comprehensive approach outlined in this article addresses the common pitfalls that traditionally plague test automation efforts and provides a robust foundation that evolves alongside your application.

By implementing this architecture, you create a testing framework with multiple layers of value:

Technical Excellence: The optimized configuration, hierarchical page objects, and component-based structure produce clean, maintainable code that follows software engineering best practices.
Process Efficiency: Centralized page management, dynamic tagging, and domain-driven organization dramatically reduce the time needed to create, run, and maintain tests, allowing your team to focus on delivering value rather than fighting fragile tests.
Organizational Scalability: As your team grows, the clear structure, consistent patterns, and logical organization make onboarding new team members faster and more effective, enabling your testing efforts to scale with your organization.
Quality Assurance: The resulting test suite provides reliable, comprehensive coverage that accurately detects regressions, giving your team confidence to release frequently and innovate rapidly.

The true measure of a testing architecture isn't how it performs on day one but how it supports your team's efforts months and years into development. This approach creates a testing ecosystem that remains valuable throughout your application's evolution, adapting to new requirements and technologies without requiring constant rewrites or maintenance overhead.

To help you get started, we've created a reference project that implements the patterns and structure described in this guide. 👉 Check out the GitHub repository here.

As Playwright continues to advance with new capabilities, this architectural foundation will integrate these innovations seamlessly, ensuring your testing strategy remains current without sacrificing stability or consistency. By adopting these patterns today, you're not just solving immediate testing challenges but creating a sustainable advantage that will benefit your project throughout its entire lifecycle.

I hope you found this article helpful! If you have any questions or feedback, feel free to leave a comment.

Let's connect! You can follow my projects on GitHub or reach out on LinkedIn.

Connect on LinkedIn: https://www.linkedin.com/in/gmeilus

See me on GitHub: https://github.com/gustavo-meilus