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.
Always remember to add a .gitignore file to your repository including a .env line so you never accidentally commit you TestDriver API key. This is important for security and to prevent exposing sensitive information. For more info see GitHub Docs.

​
How authentication works in TestDriver

  1. Store Credentials Securely:
  • Use GitHub Secrets to store sensitive information like usernames, passwords, or API keys.
  1. Pass Credentials to the Workflow:
  • Supply credentials as environment variables or directly in the workflow.
  1. Use Credentials in Tests:
  • Dynamically reference credentials in the prerun script or test files to perform authentication steps.
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)

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

version: 4.2.18
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.
  1. Secrets in the prerun Script:
  • The TD_WEBSITE secret is used to launch the browser with the correct URL.
  1. 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 ***.
  1. Dynamic Testing:
  • Easily switch between different environments (for example, staging, production) by updating the secrets.
  1. 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.