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

# Playwright

export const CenteredImage = ({src, alt, width, caption, className}) => {
  const [basePath, setBasePath] = useState("");
  useEffect(() => {
    const path = window.location.pathname;
    setBasePath(path === "/docs" || path.startsWith("/docs/") ? "/docs" : "");
  }, []);
  return <Frame caption={caption} className={className} style={{
    maxWidth: width,
    marginInline: "auto"
  }}>
			<OptimizedImage src={`${basePath}${src}`} alt={alt} />
		</Frame>;
};

Playwright is a popular end-to-end testing framework for web applications.

Namespace provides high-performance caching for [Playwright](https://playwright.dev) test runs.
By using [Cache Volumes](/docs/solutions/github-actions/caching#cache-volumes), you can cache
Playwright's browser binaries and system dependencies across workflow runs, significantly reducing
test setup time.

Making full use of the CPUs on our high-performance [Compute Platform](/docs/architecture/compute)
reduces test times by running tests faster and in parallel.

## Getting started

<Steps titleSize="h3">
  <Step title="Enable caching on your runner profile">
    Go to your [runner profile configuration](https://cloud.namespace.so/workspace/actions/profiles) and enable caching.

    <CenteredImage width={500} alt="runner profile cache configuration" src="/docs/images/github-actions/runnerprofilecaching.png" />
  </Step>

  <Step title="Add the cache action to your workflow">
    Use [`namespacelabs/nscloud-cache-action`](/docs/reference/github-actions/nscloud-cache-action) to
    cache Playwright browsers and apt packages:

    ```yaml theme={null}
    - name: Set up cache
      uses: namespacelabs/nscloud-cache-action@v1
      with:
        cache: |
          playwright
          apt
    ```

    The `playwright` cache mode stores downloaded browsers, and `apt` caches system packages so that
    `playwright install --with-deps` runs faster on subsequent runs.
  </Step>

  <Step title="Cache npm dependencies">
    In addition to Playwright browsers, you can also cache your package manager's dependencies:

    <Tabs>
      <Tab title="npm">
        For npm, add the `npm` cache mode:

        ```yaml theme={null}
        - name: Set up cache
          uses: namespacelabs/nscloud-cache-action@v1
          with:
            cache: |
              playwright
              apt
              npm
        ```
      </Tab>

      <Tab title="pnpm">
        For pnpm, add the `pnpm` cache mode:

        ```yaml theme={null}
        - name: Set up cache
          uses: namespacelabs/nscloud-cache-action@v1
          with:
            cache: |
              playwright
              apt
              pnpm
        ```
      </Tab>

      <Tab title="yarn">
        For yarn, add the `yarn` cache mode:

        ```yaml theme={null}
        - name: Set up cache
          uses: namespacelabs/nscloud-cache-action@v1
          with:
            cache: |
              playwright
              apt
              yarn
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install and run Playwright as usual">
    After setting up the cache, install dependencies and run Playwright as you normally would:

    ```yaml theme={null}
    - name: Install dependencies
      run: npm ci

    - name: Install Playwright browsers
      run: npx playwright install --with-deps

    - name: Run Playwright tests
      run: npx playwright test
    ```
  </Step>
</Steps>

## What gets cached

| Cache             | What's cached                                                         |
| ----------------- | --------------------------------------------------------------------- |
| Playwright        | Browser binaries downloaded by Playwright (Chromium, Firefox, WebKit) |
| APT               | System packages installed via apt, including browser dependencies     |
| npm / pnpm / yarn | Package manager cache for faster dependency installation              |

See the [`nscloud-cache-action`](/docs/reference/github-actions/nscloud-cache-action) documentation for
all available cache modes and configuration options.

## Next steps

### Increase the number of workers

Playwright's default configuration uses only 1 worker when it detects a CI environment. To make better use of the
available cores, you can increase this for faster test execution. A good starting point is 75% of the available cores—adjust
this depending on your workload:

```yaml theme={null}
- name: Run Playwright tests
  run: npx playwright test --workers 75%
```

You can also [configure this in your Playwright configuration](https://playwright.dev/docs/test-parallel#limit-workers).

### Upload test reports

Use [`namespace-actions/upload-artifact`](/docs/reference/github-actions/upload-artifact) to
upload Playwright's HTML report for easy debugging:

```yaml theme={null}
- uses: namespace-actions/upload-artifact@v1
  if: ${{ !cancelled() }}
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 30
```

The `if: ${{ !cancelled() }}` condition ensures the report is uploaded even when tests fail.

## Full example

Here's a complete workflow using Namespace runners with caching:

```yaml theme={null}
name: Playwright Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    timeout-minutes: 60
    runs-on: namespace-profile-playwright
    steps:
      - uses: namespacelabs/nscloud-checkout-action@v7

      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          package-manager-cache: false # Use Namespace toolchain caching instead
          cache: ""

      - name: Set up cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: |
            playwright
            apt
            npm

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test --workers 75%

      - uses: namespace-actions/upload-artifact@v1
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30
```

View the full example repository at [namespace-integration-demos/playwright](https://github.com/namespace-integration-demos/playwright).

## Advanced: pre-install browsers and system dependencies

For the fastest and most consistent job startup, pre-install Playwright's browsers and system
dependencies directly into your runner profile with a
[custom base image](/docs/solutions/github-actions/custom-base-images). This removes the browser
download and `apt-get` install from every job, so workflows start running tests immediately:

```dockerfile theme={null}
ARG NAMESPACE_BASE_IMAGE_REF=""
FROM ${NAMESPACE_BASE_IMAGE_REF} AS base

RUN npx -y playwright@1.49.0 install --with-deps chromium
```

Pin the Playwright version to match your `package.json`; if the versions diverge, Playwright will
re-download the matching browser at runtime. With this in place, your workflow can drop
`--with-deps` and run plain `npx playwright install` (or skip the install step entirely if the
versions match).