# fix-flaky-tests

The skill reads a test's failure history in Tuist, works out the root cause and patches the test. Useful when a test passes and fails at random.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 503 installs · ★ 35
- Author: tuist
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/tuist/agent-skills/tree/HEAD/skills/fix-flaky-tests/SKILL.md
- Updated: 2026-03-27
- HTML: https://affpapa.org/en/nevibecode/skills/fix-flaky-tests

## What it does

Everything runs through the Tuist CLI. The skill pulls reliability metrics with `tuist test case show <id-or-identifier> --json`, lists flaky runs with `tuist test case run list Module/Suite/TestCase --flaky --json`, then reads the failure message, file path and line number from `tuist test case run show <test-case-run-id> --json`. It opens the source at that path and edits it.

With no test given, it discovers them itself: `tuist test case list --flaky --json --page-size 50`. Tests are grouped by suite, since several flaky cases in one suite often share a cause. It also checks whether failures share a `test_run_id` — those may come from a process crash rather than a bug in the test.

The skill carries a catalogue of usual suspects: missing waits and race conditions, shared state between tests, dependence on network, time or hardcoded paths, and ordering. Crashes are read from `crash_report`, including `EXC_BREAKPOINT`, `EXC_BAD_ACCESS` and `EXC_CRASH`. Fixes are meant to be the smallest change that removes the cause, with no refactoring around it. Verification is a repeated run through `xcodebuild test` with `-test-iterations` and `-run-tests-until-failure`; the skill suggests starting at 50–100 iterations for fast unit tests and 2–5 for slower integration ones. One caveat: a race or a CI-only timing issue may not reproduce locally, and then the skill works from logs and code analysis instead.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add tuist/agent-skills --skill fix-flaky-tests -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/fix-flaky-tests/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/fix-flaky-tests/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add tuist/agent-skills --skill fix-flaky-tests -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/fix-flaky-tests/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add tuist/agent-skills --skill fix-flaky-tests -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/fix-flaky-tests/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install tuist/agent-skills fix-flaky-tests
```

2. **Manually: put the files in place**
- File: `.github/skills/fix-flaky-tests/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add tuist/agent-skills --skill fix-flaky-tests -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/tuist/agent-skills --path skills/fix-flaky-tests
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/fix-flaky-tests/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add tuist/agent-skills --skill fix-flaky-tests -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/tuist/agent-skills/tree/HEAD/skills/fix-flaky-tests/SKILL.md

## When to use it
- find the cause of a test that fails intermittently
- tell a test bug apart from a process crash on CI
- remove a test's dependence on current time or timezone
- untangle tests that share global state
- confirm a fix with repeated test runs

## Example prompts
- Investigate the failures of Module/Suite/TestCase and fix it
- Find every flaky test in the project and fix them
- Why does this test only fail on CI? Check the run history

## Similar
- [fix](https://affpapa.org/en/nevibecode/skills/fix.md) — skill · 1638 installs
- [fix-tests](https://affpapa.org/en/nevibecode/skills/fix-tests.md) — skill · 1200 installs
- [test-reliability](https://affpapa.org/en/nevibecode/skills/test-reliability.md) — skill · 1100 installs
- [debugging](https://affpapa.org/en/nevibecode/skills/akillness-debugging.md) — skill · 361 installs
- [write-tests](https://affpapa.org/en/nevibecode/skills/write-tests.md) — skill · 1200 installs
- [adding-e2e-tests](https://affpapa.org/en/nevibecode/skills/adding-e2e-tests.md) — skill · 445 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md