> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Defining Test Groups

> Organize your Playwright tests into logical groups using Playwright projects for flexible test execution

Stably runs your existing Playwright tests. We don't invent a new test runner or config – we just use your `playwright.config.ts`.

## Overview

Playwright provides many ways to select tests, and Stably supports them all. We recommend using [Playwright projects](https://playwright.dev/docs/test-projects) since they let you customize configuration for a logical group of tests.

<Note>
  You can also use projects to run the same tests in different configurations. For example, you can run the same tests in a logged-in and logged-out state.
</Note>

## Defining Projects

Projects are defined in your `playwright.config.ts` file. Each project represents a logical group of tests with its own configuration.

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'smoke',
      testMatch: '/smoke/**'
    },
    {
      name: 'release',
      testMatch: '/release/**'
    },
  ],
});
```

## Project Configuration Options

Each project can have its own configuration settings:

<AccordionGroup>
  <Accordion title="Test Selection">
    **testMatch**: Pattern to match test files

    ```typescript theme={null}
    {
      name: 'smoke',
      testMatch: '/smoke/**/*.spec.ts'
    }
    ```

    **testIgnore**: Pattern to exclude test files

    ```typescript theme={null}
    {
      name: 'all-tests',
      testMatch: '**/*.spec.ts',
      testIgnore: '**/flaky/**'
    }
    ```
  </Accordion>

  <Accordion title="Browser Configuration">
    **use**: Browser-specific settings

    ```typescript theme={null}
    {
      name: 'chromium-desktop',
      use: {
        browserName: 'chromium',
        viewport: { width: 1920, height: 1080 }
      }
    }
    ```
  </Accordion>

  <Accordion title="Dependencies">
    **dependencies**: Run other projects before this one

    ```typescript theme={null}
    {
      name: 'authenticated-tests',
      dependencies: ['setup'],
      testMatch: '/tests/**'
    }
    ```
  </Accordion>
</AccordionGroup>

## Common Project Patterns

<Tabs>
  <Tab title="By Test Type">
    Organize tests by their purpose:

    ```typescript theme={null}
    export default defineConfig({
      projects: [
        {
          name: 'smoke',
          testMatch: '/smoke/**',
          retries: 0
        },
        {
          name: 'regression',
          testMatch: '/regression/**',
          retries: 2
        },
        {
          name: 'e2e',
          testMatch: '/e2e/**',
          timeout: 120000
        }
      ]
    });
    ```
  </Tab>

  <Tab title="By Feature Area">
    Organize tests by application features:

    ```typescript theme={null}
    export default defineConfig({
      projects: [
        {
          name: 'auth',
          testMatch: '/features/auth/**'
        },
        {
          name: 'checkout',
          testMatch: '/features/checkout/**'
        },
        {
          name: 'dashboard',
          testMatch: '/features/dashboard/**'
        }
      ]
    });
    ```
  </Tab>

  <Tab title="By Environment State">
    Run the same tests in different configurations:

    ```typescript theme={null}
    export default defineConfig({
      projects: [
        {
          name: 'logged-out',
          testMatch: '/public/**',
          use: { storageState: undefined }
        },
        {
          name: 'logged-in',
          testMatch: '/authenticated/**',
          dependencies: ['setup-auth'],
          use: { storageState: 'auth.json' }
        }
      ]
    });
    ```
  </Tab>

  <Tab title="By Platform">
    Test across different browsers and devices:

    ```typescript theme={null}
    export default defineConfig({
      projects: [
        {
          name: 'desktop-chrome',
          use: { 
            browserName: 'chromium',
            viewport: { width: 1920, height: 1080 }
          }
        },
        {
          name: 'mobile-safari',
          use: {
            browserName: 'webkit',
            ...devices['iPhone 13']
          }
        }
      ]
    });
    ```
  </Tab>
</Tabs>

## Running Specific Projects

Once you've defined your projects, you can run them selectively:

### Locally

```bash theme={null}
# Run a single project
npx playwright test --project=smoke

# Run multiple projects
npx playwright test --project=smoke --project=critical
```

### On Stably Cloud

```bash theme={null}
# Run specific projects in the cloud
npx stably cloud test --project=smoke --project=release
```

## Advanced Project Setup

<AccordionGroup>
  <Accordion title="Setup and Teardown Projects">
    Use special projects for setup and teardown:

    ```typescript theme={null}
    export default defineConfig({
      projects: [
        {
          name: 'setup',
          testMatch: '/setup/**'
        },
        {
          name: 'tests',
          dependencies: ['setup'],
          testMatch: '/tests/**'
        },
        {
          name: 'teardown',
          testMatch: '/teardown/**'
        }
      ]
    });
    ```
  </Accordion>

  <Accordion title="Conditional Project Execution">
    Use environment variables to conditionally run projects:

    ```typescript theme={null}
    export default defineConfig({
      projects: [
        {
          name: 'smoke',
          testMatch: '/smoke/**'
        },
        ...(process.env.RUN_FULL_SUITE ? [{
          name: 'full-regression',
          testMatch: '/regression/**'
        }] : [])
      ]
    });
    ```
  </Accordion>

  <Accordion title="Tagging with Grep">
    Combine projects with grep patterns for fine-grained control:

    ```typescript theme={null}
    // In your test files
    test('@p0 critical login flow', async ({ page }) => {
      // test implementation
    });
    ```

    Then run:

    ```bash theme={null}
    npx stably cloud test --project=smoke --grep @p0
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Projects Focused" icon="bullseye">
    Each project should have a clear purpose and contain related tests. Avoid catch-all projects.
  </Card>

  <Card title="Use Descriptive Names" icon="tag">
    Name projects after their purpose (`smoke`, `critical`) rather than technical details.
  </Card>

  <Card title="Balance Granularity" icon="scale-balanced">
    Too many projects add complexity. Too few limit flexibility. Find the right balance for your team.
  </Card>

  <Card title="Document Your Structure" icon="book">
    Add comments in your config explaining the purpose of each project and when to use it.
  </Card>
</CardGroup>

## Next Steps

<Card title="Running Test Groups" icon="play" href="/stably-cli/run-tests">
  Learn how to run your test groups locally, in the cloud, or in CI/CD pipelines
</Card>