Skip to main content

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.

​
Automating Jira ticket creation for test failures using TestDriver CLI and Jira GitHub Actions

This guide explains how to integrate the TestDriver CLI with the Jira GitHub Action to automatically create a Jira ticket whenever a TestDriver test fails. This workflow ensures that test failures are tracked in Jira, enabling teams to address issues promptly.

​
Workflow overview

1

Run Tests with TestDriver CLI

Use the TestDriver CLI with the —headless flag to execute your test suite in a headless environment.
2

Check for Test Failures

Capture the test results and determine if any tests failed.
3

Create a Jira Ticket

Use the Jira GitHub Action to create a new ticket for each test failure, including relevant details such as the test name, failure reason, and logs.

​
Prerequisites

  1. TestDriver API Key: Store your API key as a GitHub secret (for example, TD_API_KEY).
  2. Jira API Token: Generate an API token from your Jira account and store it as a GitHub secret (for example, JIRA_API_TOKEN).
  3. Jira Base URL: Your Jira instance URL (for example, https://yourcompany.atlassian.net).
  4. Jira Project Key: The key of the Jira project where tickets will be created (for example, TEST).
  5. TestDriver CLI: The TestDriver CLI must be installed and configured in your workflow.

​
GitHub Actions workflow

Here’s a complete workflow that integrates TestDriver and Jira:

​
Workflow File:

.github/workflows/testdriver-jira.yaml
name: TestDriver with Jira Integration

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

jobs:
  run-tests:
    name: Run Tests with TestDriver
    runs-on: windows-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"

      - name: Run TestDriver
        id: testdriver
        shell: powershell
        run: |
          $exitCode = 0
          try {
            npx testdriverai@latest run testdriver/test.yaml --summary="testdriver-summary.txt"
          } catch {
            $exitCode = $LASTEXITCODE
          }

          # Set outputs for next steps
          echo "exit_code=$exitCode" >> $env:GITHUB_OUTPUT
          if ($exitCode -ne 0) {
            echo "success=false" >> $env:GITHUB_OUTPUT
          } else {
            echo "success=true" >> $env:GITHUB_OUTPUT
          }
        env:
          TD_API_KEY: ${{ secrets.TD_API_KEY }}

      - name: Check for Test Failures
        id: check-failures
        shell: powershell
        run: |
          if ("${{ steps.testdriver.outputs.success }}" -eq "false") {
            echo "TestDriver tests failed."
            echo "failure=true" >> $env:GITHUB_ENV
            
            # Copy the output file for Jira ticket
            Copy-Item testdriver-summary.txt failure-details.txt
          } else {
            echo "All tests passed."
            echo "failure=false" >> $env:GITHUB_ENV
          }

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: testdriver-results
          path: |
            testdriver-summary.txt
            failure-details.txt

  create-jira-ticket:
    name: Create Jira Ticket for Test Failures
    needs: run-tests
    runs-on: ubuntu-latest
    if: needs.run-tests.outputs.failure == 'true'
    steps:
      - name: Download test results
        uses: actions/download-artifact@v4
        with:
          name: testdriver-results

      - name: Create Jira Ticket
        uses: atlassian/gajira-create@v3
        with:
          url: ${{ secrets.JIRA_BASE_URL }}
          user: ${{ secrets.JIRA_USERNAME }}
          api-token: ${{ secrets.JIRA_API_TOKEN }}
          project: TEST # Replace with your Jira project key
          summary: "TestDriver Test Failure in ${{ github.repository }}"
          description: |
            A test failure occurred during the TestDriver workflow.

            **Repository**: ${{ github.repository }}
            **Branch**: ${{ github.ref }}
            **Commit**: ${{ github.sha }}
            **Workflow Run**: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

            **Failure Details**:
            $(cat failure-details.txt)

            Please investigate the issue and resolve it promptly.
          issuetype: Bug

​
Workflow steps explained

​
1. Run Tests with TestDriver CLI

This step runs the TestDriver CLI with the testdriver/test.yaml file.
testdriver/test.yaml
- name: Run TestDriver
  id: testdriver
  run: npx testdriverai@latest run testdriver/test.yaml
  env:
    TD_API_KEY: ${{ secrets.TD_API_KEY }}

​
2. Check for test failures

This step checks the exit code and success status from the TestDriver CLI run. If the tests failed, it sets an environment variable (failure=true) to trigger the Jira ticket creation step and prepares the output file for the Jira ticket.
testdriver/test.yaml
- name: Check for Test Failures
  id: check-failures
  run: |
    if ("${{ steps.testdriver.outputs.success }}" -eq "false") {
      echo "TestDriver tests failed."
      echo "failure=true" >> $env:GITHUB_ENV
      
      # Copy the output file for Jira ticket
      Copy-Item testdriver-output.txt failure-details.txt
    } else {
      echo "All tests passed."
      echo "failure=false" >> $env:GITHUB_ENV
    }
  shell: powershell

​
3. Create a Jira ticket

If any tests failed, the create-jira-ticket job uses the atlassian/gajira-create action to create a new Jira ticket. The ticket includes:
  • Summary: A brief description of the failure with repository information.
  • Description: Detailed information about the failure, including repository details, workflow run links, and the captured test output.
testdriver/test.yaml
- name: Create Jira Ticket
  uses: atlassian/gajira-create@v3
  with:
    url: ${{ secrets.JIRA_BASE_URL }}
    user: ${{ secrets.JIRA_USERNAME }}
    api-token: ${{ secrets.JIRA_API_TOKEN }}
    project: TEST # Replace with your Jira project key
    summary: "TestDriver Test Failure in ${{ github.repository }}"
    description: |
      A test failure occurred during the TestDriver workflow.

      **Repository**: ${{ github.repository }}
      **Branch**: ${{ github.ref }}
      **Commit**: ${{ github.sha }}
      **Workflow Run**: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

      **Failure Details**:
      $(cat failure-details.txt)

      Please investigate the issue and resolve it promptly.
    issuetype: Bug

​
Secrets configuration

Add the following secrets to your GitHub repository:
  1. TD_API_KEY: Your TestDriver API key.
  2. JIRA_API_TOKEN: Your Jira API token.
  3. JIRA_BASE_URL: Your Jira instance URL (for example, https://yourcompany.atlassian.net).
  4. JIRA_USERNAME: Your Jira account email.