Gaffer

Gaffer

cURL Guide

Upload test reports to Gaffer using cURL.

This guide shows how to upload test reports to Gaffer using cURL from the command line. This is useful for quick uploads, debugging, or integrating with custom CI/CD systems.

Prerequisites

  • A Gaffer account with a project
  • Your project's API key
  • cURL installed (available by default on macOS and most Linux distributions)

Basic Upload

The simplest upload with just a file:

curl 
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@path/to/test-report.html"

Replace YOUR_API_KEY with your actual API key, and update the file path to point to your test report.

Upload with Tags

Add metadata tags to help organize your test runs. We strongly recommend including commitSha and branch:

curl 
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@playwright-report/index.html" \
  -F 'tags={"commitSha":"abc123def456","branch":"main","test_framework":"playwright","test_suite":"e2e"}'

Tip: All tags are optional, but commitSha is strongly recommended as it helps you correlate test results with specific code changes.

Upload Multiple Files

Upload multiple files by repeating the -F "files=..." flag:

curl 
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@playwright-report/index.html" \
  -F "files=@playwright-report/data/report.json" \
  -F "files=@playwright-report/screenshots/failed-test.png" \
  -F 'tags={"commitSha":"abc123","branch":"feature/login"}'

Dynamic Git Information

You can use shell command substitution to automatically include git information:

curl 
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@test-results/junit.xml" \
  -F 'tags={"commitSha":"'"$(git rev-parse HEAD)"'","branch":"'"$(git branch --show-current)"'"}'

Common Issues

401 Unauthorized

Check that your API key is correct and properly formatted. The key should start with gfr_.

400 Bad Request - No files provided

Ensure you're using -F "files=@..." with the @ symbol before the file path. The @ tells cURL to read the file contents rather than using the path as a string value.

400 Bad Request - File too large

Individual files are limited to 50 MB, and total upload size is limited to 100 MB.

Next Steps