Skip to main content

API Access & Automation

Use API tokens to integrate TestFish with CI/CD pipelines and the Jira Forge app.

API tokens​

Generate tokens under Project → Settings → API Tokens (project level).

Available tokens​

  • CI/CD tokens – For CI pipelines to report automated test results. These tokens allow creating test runs and reporting execution results.
  • Jira Forge app tokens – For the TestFish Jira Forge app integration. These tokens provide read access to test cases, test runs, and requirements for linking with Jira issues.

Tokens can have expiry dates (30d, 90d, 1y, never) and are revocable at any time.

Automated test runs​

CI pipelines can report test results to TestFish using the @testfish/cli tool or by calling the REST API directly.

The easiest way to report test results is using the @testfish/cli package, which automatically parses JUnit XML reports and maps them to test cases.

Setup​

  1. Generate a CI/CD token in Project → Settings → API Tokens
  2. Store these secrets in your CI/CD system (e.g., GitHub Secrets): 
    TESTFISH_API_TOKEN=your_generated_token
    TESTFISH_API_URL=https://api.testfish.io
    TESTFISH_PROJECT_ID=your_project_uuid

Annotate your tests​

Annotate your test names with TestFish case IDs using the format TC-<Test case Identifier>:

// Static test case ID
test('user can login [TC-LOGIN-001]', async ({ page }) => {
  // Your test code
});

// Programmatic test case ID
test(`user can login [TC-${testCaseId}]`, async ({ page }) => {
  // Your test code
});

Report results​

Add a reporting step to your CI/CD workflow (after generating JUnit XML):

- name: Report results to TestFish
  if: always()
  run: |
    npx --yes @testfish/cli@latest report \
      --api-url "${{ secrets.TESTFISH_API_URL }}" \
      --token "${{ secrets.TESTFISH_API_TOKEN }}" \
      --project-id "${{ secrets.TESTFISH_PROJECT_ID }}" \
      --title "${{ inputs.test_run_title }}" \
      --file ./junit.xml