Playwright project configuration

Suppose the number of test grows, how will you structure and group all your tests? Which test should run when?

There's no one-fits-all solution, but here are some recommendations.

Sensitive information and preview URLs should be handled by the environment

Credentials and URL configuration don't belong into your test code. Luckily, you can always access process.env from within your tests.

// example.spec.js
test(`example test`, async ({ page }) => {
  // ...
  await page.getByLabel("User Name").fill(process.env.USERNAME);
  await page.getByLabel("Password").fill(process.env.PASSWORD);
});

And configure your tests from the command line.

USERNAME=me PASSWORD=secret npx playwright test

More granular configuration with projects

After bootstraping a new Playwright project, the projects configuration only included projects for different browsers. But it can do way more than configuring browsers!

// bootstrap projects
module.exports = defineConfig({
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },

    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
    },

    //...
  ],
});

Projects and fixtures are highly configurable on multiple levels.

Three levels of test configuration

There are three levels to configure your Playwright tests.

1. Global — config.use
2. Project — config.project.use
3. Test — test.use()

For example, to configure which browser engine, viewport size or user-agent to use, here's a playwright.config.js running Chromium by default for all tests in testDir, but runs Safari tests defined in a different project.

module.exports = defineConfig({
  testDir: "./tests",
  use: {
    // make Chrome the default test browser
    ...devices["Desktop Chrome"],
  },

  projects: [
    {
      name: "base",
    },

    {
      name: "base-webkit",
      // overwrite viewport, user-agent etc for this project
      use: { ...devices["Desktop Safari"] },
    },
});

You can run all projects or only project-specific tests.

$ npx playwright test                       # all tests run (Chrome & Safari)
$ npx playwright test --project=base        # only "base" tests in default config (Chrome)
$ npx playwright test --project=base-webkit # only "base-webkit" tests with specific settings (Safari)

Configuration via test projects and fixtures

Sometimes it makes sense to group your tests and only run them in certain situations. Some example are:

• smoke vs default tests
• fully parallel vs serial tests
• same but differently configured tests against staging or production environments

There are many possibilities to group your tests and run them with different configuration.

// playwright.config.js
// @ts-check
const { defineConfig } = require("@playwright/test");

module.exports = defineConfig({
  projects: [
    {
      name: "Smoke",
      // only run smoke tests
      testMatch: /.*smoke.spec.ts/,
      retries: 0,
    },
    {
      name: "Default",
      // don't run smoke tests
      testIgnore: /.*smoke.spec.ts/,
      retries: 2,
    },
  ],
});