Writing maintainable and reusable test code

Embracing Localized Selectors with Data Attributes

The foundation of maintainable tests lies in how you identify elements. Relying on CSS classes or deep DOM structures makes tests fragile, as these often change during refactoring or stylistic updates. Instead, use custom attributes like 'data-testid' that are dedicated solely to testing purposes. This decoupling ensures that your test logic remains agnostic to visual changes, focusing strictly on the functional identity of the element. By selecting elements through these stable identifiers, you ensure that the test suite does not break every time a designer updates a layout or changes a CSS framework. This strategy shifts the burden of maintenance from the test suite back to the component architecture, requiring developers to think about testing identifiers as a first-class citizen in the application. Always prioritize these stable attributes to provide a clear contract between your tests and your application structure, allowing for long-term consistency in your verification pipeline.

// Instead of '.login-button-primary', use a dedicated test ID
// This attribute survives CSS refactors and framework migrations
await page.getByTestId('login-submit-button').click();

Encapsulating Logic with the Page Object Model

The Page Object Model (POM) is the standard for managing complexity in larger suites. By grouping selectors and actions into dedicated classes, you centralize the knowledge of your application's UI structure. When a field name changes or a modal is updated, you only need to modify the code in one file rather than updating every test that touches that component. This abstraction layer also forces you to write more readable code, as your test scripts can invoke human-readable methods like 'loginPage.submitCredentials()' rather than manually typing out selectors. This approach treats your pages as programmable interfaces, enhancing reusability across different test scenarios. Think of the POM as an API for your application's UI, where the internal implementation details are hidden behind meaningful method signatures. This architecture dramatically simplifies the onboarding process for new developers and prevents the 'shotgun surgery' problem where a simple UI tweak forces massive changes across your entire test repository.

class LoginPage {
  constructor(page) {
    this.page = page;
    this.username = page.getByLabel('Username');
  }
  async login(user, pass) {
    await this.username.fill(user);
    await this.page.fill('input[type="password"]', pass);
    await this.page.click('button[type="submit"]');
  }
}

Leveraging Custom Fixtures for Environment Setup

Fixtures are the mechanism by which you provide pre-configured environments to your tests. Rather than duplicating setup code in 'beforeEach' blocks, you can define fixtures that inject authenticated pages, database states, or mocked network responses into your tests. A fixture runs lazily, meaning it only executes if the test actually requires it, which optimizes performance. Furthermore, fixtures can handle teardown logic automatically, ensuring that state is cleaned up without cluttering the main test body. This pattern allows for granular control over the test environment; you can easily swap a database-backed fixture for a mocked version during CI runs to increase speed and reduce flakiness. By moving complex setup logic into fixtures, you keep your test files focused strictly on the user journey. This separation of concerns allows you to build complex testing ecosystems where common infrastructure needs are defined once and inherited by any test that requires specific capabilities.

// Defining a custom fixture in playwright.config.ts or a separate file
export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/login');
    await page.fill('#user', 'admin');
    await use(page);
    // Teardown logic happens after the test ends
  }
});

Standardizing Reusable Web Components

When your application uses complex, repeated patterns like data tables, date pickers, or navigation menus, it is beneficial to create specialized component objects. Similar to the Page Object Model, these component classes encapsulate the specific behavior of a repeatable UI segment. If your application has a table that appears on five different pages, you should not redefine the logic for clicking rows or sorting columns five times. Instead, define a TableComponent class that takes a locator as a constructor argument. This locator represents the root element of the table. By doing this, your test code can instantiate multiple table components in a single view, treating them as individual objects. This modular approach promotes the 'DRY' (Don't Repeat Yourself) principle, making your codebase much smaller and easier to debug. When the table's sorting mechanism changes, you update one class, and the entire suite automatically benefits from the corrected logic, significantly reducing maintenance overhead over time.

class TableComponent {
  constructor(locator) {
    this.container = locator;
  }
  async getRow(index) {
    return this.container.locator('tr').nth(index);
  }
}

Writing Atomic Tests to Isolate Failures

An atomic test is one that performs a single task and verifies a specific outcome. When tests perform too many actions, they become fragile and difficult to debug because a single failure might be caused by any of the previous steps. By keeping tests small and focused, you ensure that failure logs point directly to the problematic interaction. Furthermore, atomic tests are easier to parallelize because they do not rely on a specific sequential state created by a 'god-test' that runs for ten minutes. If a feature fails, you only need to look at the specific atomic test for that feature to identify the regression. While some overlap is necessary, you should aim to make each test independent. This improves the reliability of your continuous integration pipeline, as a single flake in a massive, multi-step chain does not invalidate the entire suite. Keep tests lean to make the system resilient and easy to understand for any developer who maintains it.

// An atomic test focuses on one specific feature
test('should display error on invalid login', async ({ page }) => {
  await page.goto('/login');
  await page.fill('#user', 'bad-user');
  await page.click('#submit');
  await expect(page.locator('.error')).toBeVisible();
});

Interview questions

All Playwright interview questions →

Check yourself

Take the full Playwright quiz →