Folder Structure for Playwright Tests

A well-organized folder structure is essential for maintaining a scalable and maintainable test automation framework. This page outlines the recommended structure for implementing Playwright tests in the PPUX repository.

[!TIP] Follow these folder structure conventions from the beginning of your project. Refactoring a messy test structure later becomes exponentially more difficult as your test suite grows.

Overview

The PPUX repository uses a standardized folder structure that separates configuration, test files, page objects, utilities, and other resources. This organization makes it easier to locate files, understand their purpose, and maintain the codebase as it grows.

[!IMPORTANT] Consistent folder structure across teams enables easier knowledge sharing and onboarding of new team members. Adhere to these conventions unless you have a compelling reason to deviate.

Recommended Folder Structure

<rootDir>
    src
    +--config
        `-- config.json                 # Configuration for environments, user accounts and KeyVault
    +--globals
        `-- global-setup.ts             # To set something up once before running all tests
        `-- global-teardown.ts          # To run something once after all the tests
    +--handlebars
        `-- *.handlebars                # Email templates for test run notifications
    +--apps
      +--<appName>
        +--pages
          +--<POM pages related to product>  # Page Object Model files
        +--tests                        # *.test.ts test files for app
        +--utils                        # Utility libraries for app
    +--reports
        `-- weeklyReportEmail.ts        # Sends weekly email notification about test results
    +--setup
        `-- localEnvSetup.ts            # Command for setting-up local test environment
    +--utils
        `-- baseFixture.ts              # Fixtures and hook functions for tests
        `-- common.ts                   # Common constants, enums, selectors, etc.
        `-- testUtils.ts                # Major app specific utility functions
        `-- runtimeUtils.ts             # Utility functions for test runtime

   `-- .eslintrc.js                     # Linter configuration
   `-- playwright.config.ts             # Playwright configuration
   `-- package.json                     # Project dependencies and scripts
   `-- README.md                        # Project documentation
   `-- tsconfig.json                    # TypeScript configuration

[!TIP] The simplest way to get started with this structure is to use the PPUX template generator: npx @ppux/create-test-structure. This will automatically generate the standard folder structure with placeholder files.

Directory Details

/src/config

Contains configuration files used by the test framework:

• config.json: Defines environment URLs, user accounts, and KeyVault information for authentication

[!IMPORTANT] Never commit sensitive information like passwords or tokens to the config.json file. Instead, use KeyVault references or environment variables.

/src/globals

Houses scripts that run at the beginning and end of the entire test suite:

• global-setup.ts: Runs once before all tests begin, used for one-time setup operations

• global-teardown.ts: Runs once after all tests complete, used for cleanup operations

[!TIP] Use global-setup.ts for operations that should happen only once, like database seeding or resource provisioning. This is more efficient than repeating the same setup for each test.

/src/handlebars

Contains email templates for test run notifications:

• success.handlebars: Email template for successful test runs

• failure.handlebars: Email template for failed test runs

• weekly.handlebars: Template for weekly summary reports

/src/apps

This is where most of the test code lives, organized by application:

• <appName>: Folder for a specific application (e.g., make-powerapps-com, power-automate)

  • /pages: Page Object Model (POM) classes for the application’s UI

  • /tests: Test files (*.test.ts) containing actual test cases

  • /utils: Application-specific utility functions and helpers

[!IMPORTANT] Maintain a clear separation between test logic (in test files) and page interactions (in POM files). This makes tests easier to maintain when the UI changes.

/src/reports

Contains scripts for generating and sending test result reports:

• weeklyReportEmail.ts: Script that sends weekly summaries to team owners

[!TIP] Customize report templates to highlight the metrics most relevant to your team. Consider adding trend analysis to track improvement over time.

/src/setup

Contains setup utilities for the test environment:

• localEnvSetup.ts: Helps developers configure their local test environment

/src/utils

Contains shared utility files used across multiple apps:

• baseFixture.ts: Common test fixtures and hooks

• common.ts: Shared constants, enumerations, and selectors

• testUtils.ts: Utility functions for common test operations

• runtimeUtils.ts: Utilities for managing test runtime environment

[!TIP] When adding utility functions, consider if they’re application-specific (place in app/utils) or general-purpose (place in src/utils). This helps maintain a clean separation of concerns.

Root Files

• .eslintrc.js: ESLint configuration for code quality

• playwright.config.ts: Main Playwright configuration

• package.json: NPM dependencies and scripts

• README.md: Project documentation

• tsconfig.json: TypeScript compiler configuration

Best Practices

When working with this folder structure:

1. Keep tests organized by app: Each application should have its own folder under /src/apps

2. Use Page Object Models: All page interactions should be encapsulated in POM classes

3. Leverage shared utilities: Common functions should be in /src/utils to avoid duplication

4. Maintain configuration in one place: Environment URLs and other configurations should only be in config.json

5. Follow naming conventions: Use descriptive names and consistent patterns:

   • Test files: feature-name.test.ts

   • Page objects: feature-name.page.ts

   • Utility files: feature-name.utils.ts

[!IMPORTANT] Test files should focus on business scenarios, not implementation details. Abstract technical complexity into Page Objects and utility functions.

Example: Adding a New App

To add tests for a new application:

1. Create a new folder under /src/apps with your application name

2. Add the standard subdirectories:

src/apps/my-new-app/
├── pages/
│   └── home.page.ts
├── tests/
│   └── home.feature.test.ts
└── utils/
    └── app-specific.utils.ts

3. Implement your Page Object Models in the pages directory

4. Write your tests in the tests directory

5. Add any app-specific utilities in the utils directory

[!TIP] Start with a simple smoke test that verifies basic functionality before building out your complete test suite. This gives you quick feedback on your setup and helps identify early integration issues.

This structured approach ensures your tests remain maintainable as the test suite grows.