Skip to main content

Quick Start Guide

Get UnfoldCI monitoring your tests in under 5 minutes.

Prerequisites​

  • GitHub repository with tests
  • Tests that output JUnit XML format
  • Admin access to the repository

Step 1: Install GitHub App​

  1. Visit github.com/apps/unfoldci-flaky-test-autopilot
  2. Click Install
  3. Select your repositories
  4. Complete installation

Step 2: Generate API Key​

  1. Visit app.unfoldci.com
  2. Sign in with GitHub
  3. Click Settings
  4. Click Generate New API Key
  5. Copy the key immediately

Step 3: Add Secret to GitHub​

  1. Go to your repository → Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Name: FLAKY_AUTOPILOT_KEY
  4. Value: Paste your API key
  5. Click Add secret

Step 4: Add Workflow​

Create .github/workflows/tests.yml:

name: Tests with UnfoldCI

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
        # No continue-on-error needed! Jest runs ALL tests and writes complete XML

      # UnfoldCI Flaky Test Detection
      - name: Analyze Flaky Tests
        if: always()  # ← Runs even if tests failed
        id: flaky-analysis
        uses: UnfoldAI-Labs/UnfoldCI-flaky-autopilot-action@v1
        with:
          api-key: ${{ secrets.FLAKY_AUTOPILOT_KEY }}
          # results-path not needed! Auto-detects JUnit XML from common locations
      
      - name: Show Results
        if: always()
        run: |
          echo "Flaky tests detected: ${{ steps.flaky-analysis.outputs.flakes_detected }}"
          echo "Total tests analyzed: ${{ steps.flaky-analysis.outputs.tests_analyzed }}"
          echo "Dashboard: ${{ steps.flaky-analysis.outputs.dashboard_url }}"
Auto-Detection

UnfoldCI automatically finds JUnit XML files in common locations—no results-path configuration needed for Jest, pytest, Vitest, Go, and most other frameworks!

Step 5: Configure Test Output​

Ensure your tests output JUnit XML format.

Jest​

Install the reporter:

npm install --save-dev jest-junit

Add to package.json:

{
  "scripts": {
    "test": "jest --ci --reporters=default --reporters=jest-junit"
  },
  "jest-junit": {
    "outputDirectory": "test-results",
    "outputName": "junit.xml"
  }
}

pytest​

Add to pytest.ini:

[pytest]
addopts = --junitxml=test-results/junit.xml

Vitest​

Add to vitest.config.ts:

export default {
  test: {
    reporters: ['default', 'junit'],
    outputFile: {
      junit: 'test-results/junit.xml'
    }
  }
}

Step 6: Trigger First Run​

Push your changes:

git add .
git commit -m "Add UnfoldCI flaky test detection"
git push

Or manually trigger:

  1. Go to Actions tab
  2. Select your workflow
  3. Click Run workflow

Step 7: View Results​

  1. Open app.unfoldci.com
  2. Your repository should appear with test data
  3. View:
    • Health Score — Overall test reliability
    • Flaky Tests — Tests with inconsistent results
    • Recent Fixes — AI-generated PRs

What Happens Next​

After First Run​

  • Tests are recorded in the system
  • Baseline metrics established
  • Dashboard shows initial data

After 3-5 Runs​

  • Flake detection algorithm activates
  • Pass/fail patterns identified
  • Potentially flaky tests flagged

When Flaky Test Detected​

  • AI analyzes root cause
  • Fix generated automatically
  • Pull request created in your repository

Complete Working Example​

Here's a complete workflow for a JavaScript project:

name: Tests with UnfoldCI

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run JavaScript tests
        run: npm test
        # No continue-on-error needed for single framework

      # UnfoldCI Flaky Test Detection
      - name: Analyze Flaky Tests
        if: always()  # ← Runs even if tests failed
        id: flaky-analysis
        uses: UnfoldAI-Labs/UnfoldCI-flaky-autopilot-action@v1
        with:
          api-key: ${{ secrets.FLAKY_AUTOPILOT_KEY }}
          # results-path auto-detected from common locations

      - name: Show Flaky Test Results
        if: always()
        run: |
          echo "Flaky tests detected: ${{ steps.flaky-analysis.outputs.flakes_detected }}"
          echo "Total tests analyzed: ${{ steps.flaky-analysis.outputs.tests_analyzed }}"
          echo "Dashboard: ${{ steps.flaky-analysis.outputs.dashboard_url }}"

Next Steps​