---
title: "Playwright Export"
sidebarTitle: "Playwright"
description: "A comprehensive guide to integrating TestDriver with Playwright for automated test generation."
icon: "masks-theater"
---

This guide explains how to use **TestDriver CLI** to generate Playwright test scripts and integrate them into your repository using a GitHub Actions workflow. The workflow automates the process of generating Playwright tests using TestDriver's execution capabilities and can create pull requests with the generated tests.

---

## Workflow overview

1. **Run TestDriver CLI**: Execute a TestDriver test file.
2. **Lifecycle Prerun**: Automatically install Playwright and generate test scripts via `lifecycle/prerun.yaml`.
3. **Execute Test**: Run the main test logic to verify or use the generated Playwright tests.
4. **Create Pull Request**: Optional additional steps can commit changes and create a pull request for review.

---

## Prerequisites

1. **GitHub Repository**: Ensure your project is hosted on GitHub.
2. **TestDriver API Key**: Store your API key as a GitHub secret (for example, `TD_API_KEY`).
3. **Lifecycle Files**: Create `lifecycle/prerun.yaml` for Playwright installation and generation.
4. **TestDriver Test File**: Create a test file (`testdriver/test.yaml`) for your main test logic.

---

## GitHub Actions workflow

Here's the GitHub Actions workflow to automate the process:

### Workflow file: `.github/workflows/playwright.yaml`

```yaml [expandable]
name: TestDriver / Playwright

on:
  push:
    branches: ["main"]
  pull_request:
  workflow_dispatch:

permissions:
  actions: write
  contents: write
  statuses: write
  pull-requests: write

jobs:
  test:
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.ref }}

      - name: Run TestDriver
        run: npx testdriverai@latest run testdriver/test.yaml
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          FORCE_COLOR: "3"
```

---

## Workflow steps explained

### 1. **Check out repository**

The workflow checks out the repository to ensure the latest code is available for the test generation process.

```yaml
- name: Check out repository
  uses: actions/checkout@v4
  with:
    ref: ${{ github.event.ref }}
```

---

### 2. **Run TestDriver**

TestDriver CLI executes the test file in headless mode. The test file should contain commands to install Playwright and generate the test scripts.

```yaml
- name: Run TestDriver
  run: npx testdriverai@latest run testdriver/test.yaml
  env:
    TD_API_KEY: ${{ secrets.TD_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    FORCE_COLOR: "3"
```

---

### 3. **Lifecycle configuration**

Use `lifecycle/prerun.yaml` to install and launch Playwright before your test runs. This keeps the setup separate from your actual test logic:

```yaml
# lifecycle/prerun.yaml
version: 5.1.1
steps:
  - prompt: install and launch playwright
    commands:
      - command: exec
        lang: pwsh
        code: |
          npm install playwright -g
          playwright install --with-deps chromium
          npx playwright codegen --target playwright-test -o testdriver/pw-test.spec.js https://airbnb.com
```

Your main `testdriver/test.yaml` file can then focus on the actual test logic:

```yaml
# testdriver/test.yaml
version: 5.1.1
steps:
  - prompt: verify playwright test was generated
    commands:
      - command: exec
        lang: pwsh
        code: |
          if (Test-Path "testdriver/pw-test.spec.js") {
            Write-Host "Playwright test generated successfully"
          } else {
            throw "Playwright test generation failed"
          }
```

---

### 4. **Commit and create pull request**

After TestDriver generates the Playwright test files, you can use additional GitHub Actions steps to commit the changes and create a pull request:

```yaml
- name: Commit changes
  run: |
    git config --local user.email "action@github.com"
    git config --local user.name "GitHub Action"
    git add testdriver/pw-test.spec.js
    git commit -m "Generate Playwright test" || exit 0

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v5
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    commit-message: "Generate Playwright test"
    title: "TestDriver / Generate Playwright Test"
    branch: generate-playwright
    base: main
```

---

## Running the workflow

<Steps>
<Step title="Trigger the Workflow">
  - Push changes to the `main` branch.
  - Open a pull request.
  - Manually trigger the workflow using the **workflow_dispatch** event.
  </Step>
<Step title="Review the Pull Request">
  - Navigate to the **Pull Requests** tab in your GitHub repository.
  - Review the generated Playwright test script (`pw-test.spec.js`).
  </Step>

<Step title="Merge the Pull Request">
  - Once reviewed, merge the pull request to include the generated test in your repository.
</Step>
</Steps>
---

## Example output

- **Generated Test File**: `testdriver/pw-test.spec.js`
- **Pull Request**: A new pull request titled `TestDriver / Generate Playwright Test` will be created.

---

## Best practices

1. **Secure API Key**: Store the TestDriver API key as a GitHub secret to avoid exposing sensitive information.
2. **Review Generated Tests**: Always review the generated Playwright test scripts to ensure they meet your requirements.
3. **Use Lifecycle Files**: Use `lifecycle/prerun.yaml` for Playwright installation and setup to separate concerns from your main test logic.
4. **Error Handling**: Include error handling in both lifecycle and test files to manage installation and generation failures gracefully.
5. **File Organization**: Keep generated Playwright tests in a dedicated directory for better organization.

---

By following this guide, you can use TestDriver CLI to generate and manage Playwright tests in your GitHub repository through automated workflows.