Gaffer

Gaffer

README Badges

Add dynamic test health badges to your GitHub README using shields.io. Display pass rate, coverage percentage, and flaky test count.

Showcase your test health with dynamic badges powered by shields.io. Badges update automatically with each test run.

Available Badges

Gaffer provides three badge types:

Badge Example Description
Tests Tests badge Shows your test pass rate percentage
Coverage Coverage badge Shows your code coverage percentage
Flaky Flaky badge Shows the count of flaky tests detected

How It Works

Badges use the shields.io endpoint badge format. Gaffer provides public JSON endpoints that shields.io fetches to render your badges dynamically.

Badge Endpoints

Badge Endpoint
Tests /api/badges/:projectId/health.json
Coverage /api/badges/:projectId/coverage.json
Flaky /api/badges/:projectId/flaky.json

Getting Your Badge Code

The easiest way to get badge embed code is from your project settings:

  1. Go to your project in the Gaffer dashboard
  2. Navigate to Settings → Badges
  3. Choose your preferred badge style
  4. Copy the Markdown or HTML code
  5. Paste into your README

Manual Setup

You can also construct badge URLs manually. Replace YOUR_PROJECT_ID with your Gaffer project ID:

Markdown

[![Tests](https://img.shields.io/endpoint?url=https://app.gaffer.sh/api/badges/YOUR_PROJECT_ID/health.json)](https://app.gaffer.sh/projects/YOUR_PROJECT_ID)
[![Coverage](https://img.shields.io/endpoint?url=https://app.gaffer.sh/api/badges/YOUR_PROJECT_ID/coverage.json)](https://app.gaffer.sh/projects/YOUR_PROJECT_ID)
[![Flaky](https://img.shields.io/endpoint?url=https://app.gaffer.sh/api/badges/YOUR_PROJECT_ID/flaky.json)](https://app.gaffer.sh/projects/YOUR_PROJECT_ID)

HTML

<a href="https://app.gaffer.sh/projects/YOUR_PROJECT_ID">
  <img src="https://img.shields.io/endpoint?url=https://app.gaffer.sh/api/badges/YOUR_PROJECT_ID/health.json" alt="Tests">
</a>

Badge Styles

Shields.io supports multiple badge styles. Add the style parameter to customize:

Style Example Parameter
Flat (default) Flat style style=flat
Flat Square Flat square style style=flat-square
Plastic Plastic style style=plastic
For the Badge For the badge style style=for-the-badge

Badge Colors

Badge colors automatically reflect your project's health using a 5-level scale:

Tests Badge

Pass Rate Color
≥90% brightgreen
≥75% green
≥50% yellow
≥25% orange
<25% red

Coverage Badge

Coverage Color
≥80% brightgreen
≥60% green
≥40% yellow
≥20% orange
<20% red

Flaky Badge

Flaky Tests Color
0 brightgreen
1-3 yellow
4-10 orange
>10 red

When no data is available (e.g., no test runs yet), badges display "N/A" with a neutral gray color.

Caching

Badge data is cached for 5 minutes to ensure fast loading times and reduce API load. After uploading new test results, badges will update within 5 minutes.

Tip: Badge endpoints are public (no authentication required) so shields.io can fetch them directly. Your project ID is a random UUID and cannot be guessed.

Example

Here's how badges might look in a README:

my-awesome-project

Tests Coverage Flaky

A well-tested project with great coverage and no flaky tests!

Next Steps