Playwright Fixtures

Detailed explanation

Playwright fixtures are a powerful feature that allows you to define reusable test setup and teardown logic. They provide a clean and consistent environment for each test, making your tests more reliable and maintainable. Fixtures are essentially functions that return a value, and this value can then be used within your tests. Playwright manages the lifecycle of these fixtures, ensuring they are set up before the test runs and torn down after the test completes.

Benefits of Using Fixtures:

• Reduced Boilerplate: Fixtures eliminate the need to repeat setup and teardown code in every test.
• Improved Maintainability: Changes to setup logic only need to be made in one place (the fixture definition).
• Enhanced Reusability: Fixtures can be shared across multiple tests and projects.
• Parallel Test Execution: Fixtures help ensure that tests can run in parallel without interfering with each other.
• Test Isolation: Each test gets its own isolated environment, preventing state leakage between tests.
• Dependency Injection: Fixtures can depend on other fixtures, creating a dependency graph that Playwright resolves automatically.

Defining Fixtures:

Fixtures are defined using the test.fixture API. The first argument is the name of the fixture, and the second argument is a function that implements the fixture logic.

const { test } = require('@playwright/test');
 
test.fixture('loggedInPage', async ({ page }, use) => {
  // Setup: Log in to the application
  await page.goto('/login');
  await page.fill('input[name="username"]', 'testuser');
  await page.fill('input[name="password"]', 'password');
  await page.click('button[type="submit"]');
  await page.waitForSelector('.dashboard');
 
  // Use: Provide the logged-in page to the test
  await use(page);
 
  // Teardown: Log out (optional)
  await page.click('.logout');
});
 
test('access dashboard', async ({ loggedInPage }) => {
  await loggedInPage.goto('/dashboard');
  await expect(loggedInPage.locator('.dashboard')).toBeVisible();
});

In this example, loggedInPage is a fixture that logs in to the application and provides the logged-in page object to the test. The use function is crucial; it's what makes the fixture's value available to the test. Anything after the use call is considered teardown logic and will be executed after the test completes, even if the test fails.

Fixture Scope:

Fixtures can have different scopes, which determine how often they are created and torn down. The available scopes are:

• test (default): The fixture is created and torn down for each test.
• worker: The fixture is created once per worker process and shared across all tests in that worker. This is useful for expensive setup operations that don't need to be repeated for each test, such as initializing a database connection.
• package: The fixture is created once per package and shared across all tests in that package.
• global: The fixture is created once per test run and shared across all tests.

You can specify the scope of a fixture using the scope option:

test.fixture('databaseConnection', async ({ }, use) => {
  const connection = await connectToDatabase();
  await use(connection);
  await connection.close();
}, { scope: 'worker' });

Fixture Dependencies:

Fixtures can depend on other fixtures. This allows you to create complex setup scenarios by composing smaller, reusable fixtures. To declare a dependency, simply include the name of the dependency fixture as an argument to the fixture function.

test.fixture('apiContext', async ({ request }, use) => {
  const apiContext = await request.newContext({
    baseURL: 'https://api.example.com'
  });
  await use(apiContext);
});
 
test.fixture('userData', async ({ apiContext }, use) => {
  const response = await apiContext.get('/user/123');
  const userData = await response.json();
  await use(userData);
});
 
test('verify user data', async ({ userData }) => {
  expect(userData.name).toBe('John Doe');
});

In this example, the userData fixture depends on the apiContext fixture. Playwright will automatically create the apiContext fixture before creating the userData fixture.

Overriding Fixtures:

Playwright allows you to override fixtures at different levels:

• Test-level: You can override a fixture for a specific test by providing a new implementation in the test function.
• Suite-level: You can override a fixture for all tests within a test suite using test.describe.configure.
• Project-level: You can override a fixture for all tests within a project in your Playwright configuration file.

Overriding fixtures can be useful for testing different scenarios or for providing mock implementations of dependencies.

Practical Implementation and Best Practices:

• Keep Fixtures Focused: Each fixture should have a single, well-defined responsibility. Avoid creating overly complex fixtures that do too much.
• Use Descriptive Names: Choose fixture names that clearly indicate their purpose.
• Consider Scope Carefully: Select the appropriate scope for each fixture based on how often it needs to be created and torn down. worker scope is excellent for database connections or browser contexts that can be reused.
• Handle Errors Gracefully: Implement error handling in your fixtures to prevent tests from failing due to unexpected errors during setup or teardown.
• Use auto: true for Global Setup: For fixtures that perform global setup tasks that need to run before any tests, you can use the auto: true option. This will automatically run the fixture before all tests, even if it's not explicitly used in any test.
• Leverage test.step for Clarity: Within fixtures, use test.step to clearly delineate different stages of setup and teardown. This improves readability and debugging.

Example: Database Fixture

const { test } = require('@playwright/test');
const { Pool } = require('pg');
 
test.fixture('db', async ({ }, use) => {
  const pool = new Pool({
    user: 'testuser',
    host: 'localhost',
    database: 'testdb',
    password: 'testpassword',
    port: 5432,
  });
 
  const client = await pool.connect();
 
  await test.step('Setup: Create test table', async () => {
    await client.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(255));');
  });
 
  await use(client);
 
  await test.step('Teardown: Drop test table', async () => {
    await client.query('DROP TABLE IF EXISTS users;');
    client.release();
    await pool.end();
  });
}, { scope: 'worker' });
 
test('insert and retrieve user', async ({ db }) => {
  await db.query('INSERT INTO users (name) VALUES ($1)', ['Alice']);
  const result = await db.query('SELECT * FROM users WHERE name = $1', ['Alice']);
  expect(result.rows.length).toBe(1);
  expect(result.rows[0].name).toBe('Alice');
});

This example demonstrates a worker-scoped fixture that manages a PostgreSQL database connection. The fixture creates a test table before the tests run and drops it after the tests complete.

In conclusion, Playwright fixtures are a powerful tool for managing test setup and teardown. By using fixtures effectively, you can write more reliable, maintainable, and reusable tests. Understanding the different fixture scopes, dependencies, and overriding mechanisms is essential for leveraging the full potential of this feature.

Further reading

• Playwright Fixtures Documentation
• Playwright Test API