# Debugging Failures

Diagnose a failing Ginkgo suite as an agent, always run with --json-report into a...

- Repository: https://github.com/onsi/ginkgo (9071 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add onsi/ginkgo --skill debugging-failures -g -a claude-code -y`
Codex: `npx skills add onsi/ginkgo --skill debugging-failures -g -a codex -y`
Cursor: `npx skills add onsi/ginkgo --skill debugging-failures -g -a cursor -y`
Gemini CLI: `npx skills add onsi/ginkgo --skill debugging-failures -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add onsi/ginkgo`

## Description

Diagnose a failing Ginkgo suite as an agent, always run with --json-report into a predictable temp/gitignored location, read the terminal verdict line, then use jq to extract structured failure details (name, message, file:line, panic value, captured logs). Covers the panicked-vs-failed trap, panic locations pointing into the Go runtime, parallel output interleaving, reproducing with --seed, and progress reports for hangs. Use when a suite failed and you need to know why. Also invokable as /ginkgo:debugging-failures.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debugging Ginkgo failures (especially as an agent)

Ginkgo's terminal output is good for a human; for *programmatic* diagnosis, prefer a hybrid: **terminal for the verdict, JSON + `jq` for the details.** This is empirically the most reliable, lowest-token workflow. Docs: <https://onsi.github.io/ginkgo/#reporting-and-profiling-suites>.

## The workflow: one run, JSON-first diagnosis

```bash
# One invocation gives you BOTH the human verdict on the terminal AND a structured report.
# --json-report does NOT suppress console output, so you don't pay for two runs.
ginkgo -r -p --no-color --json-report=report.json --output-dir=.ginkgo-report
```

1. **Read the terminal tail** for the one-line verdict: `FAIL! -- 5 Passed | 6 Failed | 1 Pending | 1 Skipped`. Cheap, immediate.
2. **If there are failures, query the JSON with `jq`** (filters below) to get exactly the failing specs, stable, addressable, order-independent.
3. **Clean up** the report dir when done.

Why hybrid and not one or the other:
- **Terminal-only** is brittle to parse (free-form text) and, **under `-p`, interleaves failures in nondeterministic order**.
- **JSON-only** is wasteful if you dump it: the full `report.json` is ~9× the tokens of the terminal output. A `jq` failures-only extraction is a fraction of either. The discipline is *filter, don't dump*.

## Where the JSON lands (use --output-dir deliberately)

The rest: https://github.com/onsi/ginkgo/blob/HEAD/plugins/ginkgo/skills/debugging-failures/SKILL.md