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

# Authentication

> Learn how to handle authentication workflows in TestDriver using GitHub Actions.

This guide explains how to handle **authentication workflows** in **TestDriver** using GitHub Actions. It covers securely passing credentials (for example, usernames and passwords) to the TestDriver action and using them in both the `prerun` script and test files. Save these locally in your `.env` file and use them in CI as GitHub secrets.

<GitignoreWarning />

***

## How authentication works in TestDriver

1. **Store Credentials Securely**:

* Use GitHub Secrets to store sensitive information like usernames, passwords, or API keys.

2. **Pass Credentials to the Workflow**:

* Supply credentials as environment variables or directly in the workflow.

3. **Use Credentials in Tests**:

* Dynamically reference credentials in the `prerun` script or test files to perform authentication steps.

## Step 1: Store credentials in GitHub secrets

1. Navigate to your repository's **Settings** > **Secrets and variables** > **Actions**.
2. Add the following secrets:
   * **`TD_USERNAME`**: The username for login.
   * **`TD_PASSWORD`**: The password for login.
   * **`TD_API_KEY`**: Your TestDriver API key.
   * **`TD_WEBSITE`**: The URL of the website to test.

## Step 2: Pass credentials to the workflow

Secrets are passed to the workflow using the `secrets` context. They can be supplied as:

* **Environment Variables**: Passed via the `env` block.
* **Inline in the `prerun` Script**: Used directly in the script.

### Example GitHub Actions workflow (adapt for your CI/CD platform)

```yaml workflows/td-auth.yml focus={17-24} theme={null}
name: TestDriver / Authentication

on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

jobs:
  test-authentication:
    name: Test Authentication
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run Authentication Test
        run: npx testdriverai@latest run testdriver/authentication.yaml
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}
          TD_USERNAME: ${{ secrets.TD_USERNAME }}
          TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
          TD_WEBSITE: ${{ secrets.TD_WEBSITE }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          FORCE_COLOR: "3"
```

## Step 3: Use credentials in test files

Secrets can be referenced in the test file using placeholders (for example, `${TD_USERNAME}` and `${TD_PASSWORD}`).

### Example test file:

```yaml login.yaml highlight={9, 10, 15, 16} theme={null}
version: 6.0.0
steps:
  - prompt: Log in to the application
    commands:
      - command: hover-text
        text: Email
        description: Email input field
        action: click
      - command: type
        text: ${TD_USERNAME}
      - command: hover-text
        text: Password
        description: Password input field
        action: click
      - command: type
        text: ${TD_PASSWORD}
      - command: hover-text
        text: Log In
        description: Log In button
        action: click
      - command: assert
        expect: The dashboard is displayed
```

## How it works together

1. **Secrets in the Workflow**:

* Secrets like `TD_USERNAME` and `TD_PASSWORD` are passed as environment variables to the TestDriver action.

2. **Secrets in the `prerun` Script**:

* The `TD_WEBSITE` secret is used to launch the browser with the correct URL.

3. **Secrets in the Test File**:

* The test file dynamically references the secrets to fill in login credentials during the test.

## Benefits of using authentication in TestDriver

1. **Secure Handling of Credentials**:

* Secrets are encrypted and not exposed in logs.
* Even if printed, they appear as `***`.

2. **Dynamic Testing**:

* Easily switch between different environments (for example, staging, production) by updating the secrets.

3. **Reusability**:

* Use the same workflow and test files across multiple repositories or environments.

***

By securely passing credentials and using them in the `prerun` script and test files, you can automate authentication workflows in TestDriver while ensuring sensitive information remains protected.