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

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 --headless
        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.
- 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.
- name: Run TestDriver
  run: npx testdriverai@latest run testdriver/test.yaml --headless
  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:
# 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:
# 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:
- 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

1

Trigger the Workflow

  • Push changes to the main branch.
  • Open a pull request.
  • Manually trigger the workflow using the workflow_dispatch event.
2

Review the Pull Request

  • Navigate to the Pull Requests tab in your GitHub repository.
  • Review the generated Playwright test script (pw-test.spec.js).
3

Merge the Pull Request

  • Once reviewed, merge the pull request to include the generated test in your repository.

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.