Principle:Microsoft Playwright Test File Creation
| Knowledge Sources | |
|---|---|
| Domains | Testing, Browser_Automation |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Test file creation is the process of structuring test code into executable test cases with grouping, lifecycle hooks, and fixture injection to produce maintainable and well-organized test suites.
Description
The fundamental unit of a test suite is the test case: a named block of code that exercises a specific behavior and verifies an expected outcome. However, individual test cases rarely exist in isolation. They are organized into groups (often called "describe" blocks or "suites"), share common setup and teardown logic through lifecycle hooks, and receive dependencies through a fixture injection mechanism.
Effective test file creation involves several organizational decisions. Tests should be grouped by feature or user flow so that failures are easy to locate and understand. Common setup logic (such as navigating to a page or authenticating a user) should be extracted into beforeEach hooks to avoid duplication. Complex, reusable setup that goes beyond simple navigation should be encapsulated as fixtures, which provide a dependency injection mechanism that is both explicit and composable.
The structure of test files also affects execution characteristics. Most modern test runners execute tests within a file sequentially by default but run different test files in parallel. This means that tests within a single file can share state through hooks, while tests across files are isolated. Understanding this execution model is critical for writing tests that are reliable and do not interfere with each other.
Usage
Test file creation is performed continuously as new features are developed or existing features are modified. A new test file is typically created for each logical feature area or user workflow. Within that file, related tests are grouped using describe blocks, and shared setup is extracted into hooks. Test files should be created whenever a new page, component, or API endpoint needs automated coverage.
Theoretical Basis
Test file organization follows a hierarchical containment model:
Level 1 -- Test File: The outermost container. Each file represents an independent execution unit. Files are discovered by the test runner through glob patterns (e.g., **/*.spec.ts) and may be distributed across parallel workers.
Level 2 -- Test Suite (Describe Block): A named grouping within a file. Suites can be nested to arbitrary depth, creating a tree structure. Each suite can have its own lifecycle hooks that apply only to tests within that suite.
Level 3 -- Lifecycle Hooks: Functions that run at specific points in the test lifecycle:
- Before All: Runs once before all tests in a suite. Used for expensive, shared setup (e.g., seeding a database).
- Before Each: Runs before each individual test. Used for per-test setup (e.g., navigating to a page).
- After Each: Runs after each individual test. Used for per-test cleanup.
- After All: Runs once after all tests in a suite. Used for shared teardown.
Level 4 -- Test Case: The atomic unit of testing. Each test case has a title (used for identification and filtering), an optional set of annotations (e.g., skip, slow, fixme), and a body function that receives injected fixtures and performs actions and assertions.
Level 5 -- Fixtures: A dependency injection mechanism that provides test cases with pre-configured resources (e.g., a browser page, an authenticated API client). Fixtures are declared in the test function signature and are automatically set up before the test runs and torn down after it completes.
The relationship between these levels can be expressed as:
File
Suite ("describe")
beforeEach hook
Test Case 1 (receives fixtures)
Test Case 2 (receives fixtures)
Nested Suite
Test Case 3
afterEach hook