Lifecycle Files

Overview

Lifecycle files are YAML files placed in your repository’s lifecycle/ directory. TestDriver automatically executes these files during the appropriate phases:

lifecycle/provision.yaml: Executed when a new sandbox is created
lifecycle/prerun.yaml: Executed before tests run
lifecycle/postrun.yaml: Executed after tests complete

File Structure

All lifecycle files follow the standard TestDriver YAML format:

version: 6.0.0
steps:
  - prompt: description of what this step does
    commands:
      - command: exec
        lang: pwsh
        code: |
          # Your PowerShell commands here
      - command: wait-for-text
        text: "Expected text"
        timeout: 30000

Provision Scripts

The lifecycle/provision.yaml file is executed when a new sandbox is created. This is ideal for installing dependencies, setting up the environment, or preparing the system for testing.

Example

lifecycle/provision.yaml

version: 6.0.0
steps:
  - prompt: setup testing environment
    commands:
      - command: exec
        lang: pwsh
        code: |
          Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" -ArgumentList @(
            "--start-maximized",
            "--disable-infobars",
            "--disable-fre",
            "--no-default-browser-check",
            "--no-first-run",
            "--guest",
            "${TD_WEBSITE}"
          )
      - command: wait-for-text
        text: ${TD_WEBSITE}
        timeout: 60000

Common provision tasks:

Installing software dependencies
Setting up browser extensions
Configuring system settings
Downloading test data or assets

Prerun Scripts

The lifecycle/prerun.yaml file is executed before each test run irrespective of whether its a new sandbox or an already running one. This is useful for preparing the immediate test environment.

Example

lifecycle/prerun.yaml

version: 6.0.0
session: 67f00511acbd9ccac373edf7
steps:
  - prompt: start dashcam
    commands:
      - command: exec
        lang: pwsh
        code: dashcam track --name=TestDriver --type=app --pattern="C:\Users\testdriver\Documents\testdriver.log"
      - command: exec
        lang: pwsh
        code: dashcam start

Common prerun tasks:

Opening applications or browsers
Navigating to starting pages
Clearing application state
Starting monitoring tools
Setting environment variables

Postrun Scripts

The lifecycle/postrun.yaml file is executed after tests complete. This is useful for cleanup tasks, generating reports, or capturing final state information.

Example

lifecycle/postrun.yaml

version: 6.0.0
steps:
  - prompt: cleanup and generate reports
    commands:
      - command: exec
        lang: pwsh
        code: dashcam -t 'demo-test-title' -p # use '${TD_THIS_FILE}' to dynamically set the title for the recording

Common postrun tasks:

Generating test reports
Capturing screenshots or logs
Cleaning up temporary files
Stopping background processes
Uploading artifacts

Environment Variables

Lifecycle files have access to TestDriver environment variables:

${TD_WEBSITE}: The target website URL
${TD_THIS_FILE}: Current test file name
${TD_API_KEY}: Your TestDriver API key
Custom variables defined in your workflow

Using variables in lifecycle files:

version: 6.0.0
steps:
  - prompt: setup with custom variables
    commands:
      - command: exec
        lang: pwsh
        code: |
          Write-Host "Testing website: ${TD_WEBSITE}"
          Write-Host "Current test: ${TD_THIS_FILE}"
          # Your setup commands here

Best Practices

Keep lifecycle files focused

Each lifecycle file should have a specific purpose:

Provision: System-level setup
Prerun: Test preparation
Postrun: Cleanup and reporting

Use appropriate commands

Use exec with lang: pwsh for system commands
Use TestDriver commands (wait-for-text, hover-text, etc.) for UI interactions
Include appropriate timeouts for reliability

Error handling

Include checks to verify operations completed successfully:

- command: exec
  lang: pwsh
  code: |
    if (!(Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe")) {
      throw "Chrome not found"
    }
    Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe"

Performance considerations

Keep provision scripts efficient to minimize sandbox setup time
Cache dependencies when possible
Use lightweight operations in prerun/postrun scripts

File Placement

Place lifecycle files in your repository’s root directory:

your-project/
├── testdriver/
│   ├── demo-test.yaml
│   └── lifecycle/
│       ├── provision.yaml
│       ├── prerun.yaml
│       └── postrun.yaml
│   ├── screenshots/
│   │   └──
│   └── snippets/
│       └──

Execution Order

When TestDriver runs, lifecycle files execute in this order:

Provision (once per sandbox creation)
Prerun (before each test)
Your test files
Postrun (after each test)

Troubleshooting

Lifecycle files not executing

Verify files are in the testdriver/lifecycle/ directory
Check YAML syntax is valid
Ensure version number is specified
Verify file permissions in your repository

Commands failing

Check PowerShell syntax for exec commands
Verify file paths exist on the target system
Add error handling and logging
Use appropriate timeouts for operations

Overview

Get Started

Examples

Guide

Reference

Overview

File Structure

Provision Scripts

Example

Common provision tasks:

Prerun Scripts

Example

Common prerun tasks:

Postrun Scripts

Example

Common postrun tasks:

Environment Variables

Using variables in lifecycle files:

Best Practices

Keep lifecycle files focused

Use appropriate commands

Error handling

Performance considerations

File Placement

Execution Order

Troubleshooting

Lifecycle files not executing

Commands failing

​Overview

​File Structure

​Provision Scripts

​Example

​Common provision tasks:

​Prerun Scripts

​Example

​Common prerun tasks:

​Postrun Scripts

​Example

​Common postrun tasks:

​Environment Variables

​Using variables in lifecycle files:

​Best Practices

​Keep lifecycle files focused

​Use appropriate commands

​Error handling

​Performance considerations

​File Placement

​Execution Order

​Troubleshooting

​Lifecycle files not executing

​Commands failing

Overview

File Structure

Provision Scripts

Example

Common provision tasks:

Prerun Scripts

Example

Common prerun tasks:

Postrun Scripts

Example

Common postrun tasks:

Environment Variables

Using variables in lifecycle files:

Best Practices

Keep lifecycle files focused

Use appropriate commands

Error handling

Performance considerations

File Placement

Execution Order

Troubleshooting

Lifecycle files not executing

Commands failing