Prerequisites
Before diving into Playwright automation, ensure your development environment meets the following requirements. A stable Node.js version is crucial; specifically, Node.js 24.x is recommended and can be enforced via the engines field in your package.json. For package management, npm is the standard. While not strictly required for local development, Docker is a valuable optional dependency for creating consistent, containerized environments for CI/CD pipelines. This ensures that tests run identically across different stages of your deployment process, minimizing environment-related failures.
Quick Setup
Getting your Playwright project up and running is straightforward. Begin by navigating to your repository's root directory. Execute npm ci to install all project dependencies. This command is preferred over npm install in CI/CD environments as it installs exact versions specified in the package-lock.json file, guaranteeing reproducible builds. After dependencies are installed, you need to set up Playwright's browsers and core components. Run npx playwright install --with-deps. This command downloads the necessary browser binaries (Chromium, Firefox, WebKit) and installs Playwright's internal dependencies, preparing the framework for test execution.
Execution Commands
Once setup is complete, you can execute your Playwright tests. The primary command for running tests is npx playwright test. This command will discover and run all test files in your project according to Playwright's default configuration. You can specify specific test files or directories by providing paths as arguments, for example, npx playwright test tests/login.spec.ts. To run tests in headed mode, which opens a browser window to show the test execution, use the --headed flag: npx playwright test --headed. For debugging purposes, the --debug flag is invaluable. It pauses execution at each step, allowing you to inspect the state of the application and the test.
Playwright also offers powerful modes for debugging and inspection. The --trace option, when set to 'on' or 'retain-on-failure', captures detailed execution traces, including DOM snapshots, network requests, and console logs. This trace is indispensable for diagnosing failures. Using npx playwright test --trace=on --screenshot=only-on-failure combines trace capture with screenshots only when a test fails, providing a comprehensive debugging package. For more interactive debugging, the Playwright Inspector provides a GUI to step through tests, inspect elements, and view execution logs. Launch it with npx playwright test --ui.
Environment Variables and Configuration
Managing environment-specific configurations is key to robust automation. Playwright allows extensive customization through its configuration file, typically named playwright.config.ts (or .js). This file defines project settings, test directories, reporter configurations, and browser options. For managing environment variables, such as API endpoints or credentials, you can leverage Node.js's built-in process.env object. Many projects integrate libraries like dotenv to load variables from a .env file into process.env during local development. In CI/CD environments, these variables are typically set directly as environment variables or through the CI/CD platform's secrets management system.
For instance, you might define a base URL in your playwright.config.ts file like this: baseURL: process.env.BASE_URL || 'http://localhost:3000'. This ensures that tests run against the correct environment, whether it's a local development server, a staging environment, or production. The configuration file supports multiple projects, allowing you to define different test suites with distinct configurations (e.g., mobile emulation, specific browsers, different base URLs) within a single file. This modular approach simplifies managing complex testing scenarios and ensures consistency across your automation efforts.
Output Artifacts
Playwright generates several types of output artifacts that are essential for analyzing test results and debugging failures. Test reports, configured via the reporter option in playwright.config.ts, provide a summary of test execution. Common reporters include list for simple console output, html for a detailed interactive report, and junit for integration with CI/CD systems. The HTML reporter, in particular, offers a rich interface with test status, duration, error messages, and links to detailed traces and screenshots.
Screenshots and traces are automatically captured when tests fail if configured to do so. Screenshots provide a visual snapshot of the application state at the point of failure, making it easier to identify UI defects. Traces offer a granular, step-by-step replay of the test execution, including network activity, console logs, and DOM snapshots. These artifacts are typically saved in an test-results directory by default. For CI/CD pipelines, it's crucial to configure these reporters and artifact locations correctly to ensure that results are published and accessible. For example, setting reporter: 'html' will generate an index.html file in the test-results directory, which can be uploaded as a build artifact.
CI/CD Integration
Integrating Playwright into your Continuous Integration and Continuous Deployment (CI/CD) pipeline is a key step towards automated quality assurance. The process typically involves setting up a build job that checks out your code, installs dependencies using npm ci, and then executes Playwright tests. For optimal performance and consistency, running Playwright tests within a Docker container is highly recommended. This ensures that the test environment is isolated and reproducible, regardless of the host system's configuration.
The CI/CD pipeline should be configured to capture and store test artifacts, such as HTML reports, screenshots, and traces. This allows developers and QA engineers to review test results directly within the CI/CD platform. When configuring your CI job, ensure that Playwright browsers are installed within the container or that you are using a Docker image that already includes them. Environment variables for different stages (e.g., staging, production) should be managed securely through the CI/CD platform's secrets management features. For example, a GitHub Actions workflow might include steps to install browsers, run tests with specific environment variables, and then upload the generated HTML report as an artifact.
Conclusion
This runbook provides a foundational framework for setting up and executing Playwright automation. By adhering to these guidelines for prerequisites, setup, execution, environment configuration, and artifact management, teams can accelerate onboarding, standardize their automation practices, and ensure reliable test execution within CI/CD pipelines. The detailed output artifacts and integration strategies empower development teams to maintain high-quality software through robust, automated testing.