Run Tests Endpoint

Trigger Bug0 test execution programmatically.

Endpoint

POST https://app.bug0.com/api/run-tests

Authentication

Include one of:

• x-api-key header with your project API key
• x-bug0-service-token header with service token

Request

Headers

*One authentication header is required.

Body Parameters

Finding Your Project ID

Your project ID is in the URL when viewing a project:

https://app.bug0.com/projects/[PROJECT_ID]/...

Examples

Basic Request

Trigger tests with default project settings:

curl -X POST https://app.bug0.com/api/run-tests \
  -H "x-api-key: bug0_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "507f1f77bcf86cd799439011"
  }'

With Custom URL

Test a preview deployment:

curl -X POST https://app.bug0.com/api/run-tests \
  -H "x-api-key: bug0_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "507f1f77bcf86cd799439011",
    "url": "https://preview-pr-42.vercel.app"
  }'

With Git Information

For GitHub integration (PR comments, commit status):

curl -X POST https://app.bug0.com/api/run-tests \
  -H "x-api-key: bug0_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "507f1f77bcf86cd799439011",
    "url": "https://preview-pr-42.vercel.app",
    "gitCommitSha": "abc123def456789",
    "gitBranch": "feature/new-checkout",
    "prNumber": "42",
    "owner": "your-org",
    "repo": "your-repo"
  }'

Full Example (All Parameters)

curl -X POST https://app.bug0.com/api/run-tests \
  -H "x-api-key: bug0_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "507f1f77bcf86cd799439011",
    "url": "https://preview-pr-42.vercel.app",
    "gitCommitSha": "abc123def456789",
    "gitBranch": "feature/new-checkout",
    "prNumber": "42",
    "owner": "your-org",
    "repo": "your-repo"
  }'

Response

Success (200)

{
  "success": true,
  "message": "Tests triggered successfully",
  "executionId": "exec_abc123def456"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Missing required parameter: projectId"
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid API key"
}

403 Forbidden

{
  "success": false,
  "error": "API key does not have access to this project"
}

404 Not Found

{
  "success": false,
  "error": "Project not found"
}

429 Rate Limited

{
  "success": false,
  "error": "Rate limit exceeded. Try again later."
}

Execution Flow

When you call this endpoint:

1. Validation - Parameters are validated
2. Authentication - API key is verified
3. Job Creation - Test execution job is queued
4. Response - Execution ID is returned immediately
5. Execution - Tests run asynchronously
6. Notifications - Results sent to configured channels

What Gets Executed

When triggered via API:

• Published steps are executed (not drafts)
• Login suites run first
• Regular suites run in order
• Cleanup suites run last
• Results sent to integrations

URL Override Behavior

When url is provided:

• Overrides project's base URL for this run only
• Login suites navigate to this URL
• All tests use this as the starting point
• Does not change project settings

GitHub Integration

For PR comments and commit status, ensure:

1. GitHub integration is connected in Bug0
2. owner and repo match the connected repository
3. gitCommitSha is a valid commit
4. prNumber is a valid open PR (for comments)

Code Examples

Node.js

const response = await fetch('https://app.bug0.com/api/run-tests', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.BUG0_API_KEY
  },
  body: JSON.stringify({
    projectId: process.env.BUG0_PROJECT_ID,
    url: deploymentUrl,
    gitCommitSha: process.env.GITHUB_SHA,
    gitBranch: process.env.GITHUB_REF_NAME
  })
});

const result = await response.json();
console.log('Execution ID:', result.executionId);

Python

import requests
import os

response = requests.post(
    'https://app.bug0.com/api/run-tests',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': os.environ['BUG0_API_KEY']
    },
    json={
        'projectId': os.environ['BUG0_PROJECT_ID'],
        'url': deployment_url,
        'gitCommitSha': os.environ.get('GITHUB_SHA'),
        'gitBranch': os.environ.get('GITHUB_REF_NAME')
    }
)

result = response.json()
print(f"Execution ID: {result['executionId']}")

GitHub Actions

- name: Trigger Bug0 Tests
  run: |
    curl -X POST https://app.bug0.com/api/run-tests \
      -H "x-api-key: ${{ secrets.BUG0_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "projectId": "${{ secrets.BUG0_PROJECT_ID }}",
        "url": "${{ env.DEPLOY_URL }}",
        "gitCommitSha": "${{ github.sha }}",
        "gitBranch": "${{ github.ref_name }}",
        "prNumber": "${{ github.event.pull_request.number }}"
      }'