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

# Playwright Export

> A comprehensive guide to integrating TestDriver with Playwright for automated test generation.

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] theme={null}
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 theme={null}
- 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 theme={null}
- 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 theme={null}
# 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 theme={null}
# 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 theme={null}
- 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.