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

# Reporting Failed Tests to Jira

> Step-by-step instructions to integrate TestDriver with Jira for automated test failure tracking in CI/CD workflows.

# 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

<Steps>
  <Step title="Run Tests with TestDriver CLI">
    Use the TestDriver CLI with the --headless flag to execute your test suite
    in a headless environment.
  </Step>

  <Step title="Check for Test Failures">
    Capture the test results and determine if any tests failed.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

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

```yaml .github/workflows/testdriver-jira.yaml [expandable] theme={null}
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.

```yaml testdriver/test.yaml theme={null}
- 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.

```yaml testdriver/test.yaml theme={null}
- 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.

```yaml testdriver/test.yaml theme={null}
- 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.

***