---
title: "Lifecycle Files"
sidebarTitle: "Lifecycle Files"
description: "Learn how to customize TestDriver execution with lifecycle files for setup, provisioning, and cleanup."
icon: "wrench"
---

---

## 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:

```yaml
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

```yaml 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

```yaml 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

```yaml 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:

```yaml highlight={8, 9}
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`](/commands/exec) with `lang: pwsh` for system commands
- Use TestDriver commands ([`wait-for-text`](/commands/wait-for-text), [`hover-text`](/commands/hover-text), etc.) for UI interactions
- Include appropriate timeouts for reliability

### Error handling

Include checks to verify operations completed successfully:

```yaml
- 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:

1. **Provision** (once per sandbox creation)
2. **Prerun** (before each test)
3. **Your test files**
4. **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/exec) commands
- Verify file paths exist on the target system
- Add error handling and logging
- Use appropriate timeouts for operations