Skip to main content
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
        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
  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.
⌘I