README Badges

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		Shows your test pass rate percentage
Coverage		Shows your code coverage percentage
Flaky		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)		style=flat
Flat Square		style=flat-square
Plastic		style=plastic
For the Badge		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%
≥75%
≥50%
≥25%
<25%

Coverage Badge

Coverage	Color
≥80%
≥60%
≥40%
≥20%
<20%

Flaky Badge

Flaky Tests	Color
0
1-3
4-10
>10

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

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

Next Steps

• Getting Started - Set up your first project
• Analytics & Metrics - Understand your test health data
• Slack Integration - Get test results in Slack