# Detox

> Hunt down and fix flaky tests. Use when a test suite fails intermittently, CI needs re-runs to go green, or the user wants to know which tests are flaky versus genuinely broken — and why.

- **Type:** Skill
- **Install:** `agentstack add skill-tokyubevoxelverse-detox-detox`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tokyubevoxelverse](https://agentstack.voostack.com/s/tokyubevoxelverse)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tokyubevoxelverse](https://github.com/tokyubevoxelverse)
- **Source:** https://github.com/tokyubevoxelverse/detox

## Install

```sh
agentstack add skill-tokyubevoxelverse-detox-detox
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Detox

A flaky test is worse than a missing test: it trains everyone to ignore red. Your job is to separate flaky from broken, diagnose each flake's *root cause class*, and fix the cause — never the symptom.

## Banned fixes

Retry wrappers, longer sleeps, and `skip` are not fixes; they are how flakes become permanent residents. The only acceptable retry is around a call to a genuinely external system the test cannot control — and that usually means the test should be mocking it instead.

## Phase 1 — Census

Run the full suite repeatedly — default 5 runs, more if runs are cheap — and build a per-test pass/fail matrix.

- **Fails every run** → broken, not flaky. Report separately; out of scope unless asked.
- **Fails some runs** → flaky. This is the target list, ranked by failure rate.
- Record conditions per run: ordering, parallelism, seed, timing — the variance between a passing and failing run often names the culprit by itself.

## Phase 2 — Diagnose each flake

Isolate, then classify. Standard experiments:

| Experiment | If behavior changes → |
|---|---|
| Run the test **alone** vs. after the full suite | Shared state / test-order dependence |
| Run the suite in **random order** / different parallelism | Order dependence, resource contention (ports, files, DB rows) |
| Run with a **fixed seed** / frozen clock | Unseeded randomness, time-of-day or timezone dependence |
| Run **repeatedly in a tight loop** | Race conditions, timing assumptions, hardcoded timeouts |
| Run with network blocked / observed | Real network calls hiding in a "unit" test |

Read the failing assertion under each hypothesis: a flake almost always belongs to one of six families — shared state, ordering, timing/races, unseeded randomness, clock/timezone, external systems (network, filesystem, ports).

## Phase 3 — Fix the cause

Match the fix to the family: proper setup/teardown isolation for shared state; explicit awaiting or synchronization points instead of sleeps for races; injected/frozen clocks; seeded randomness; mocks or test doubles for external systems; per-test unique resources (temp dirs, ephemeral ports) for contention. The fix should make the test *deterministic*, not tolerant.

## Phase 4 — Prove it

A fix isn't proven by one green run. Run the fixed test **20+ times, including under the conditions that made it fail** (full-suite ordering, parallelism, tight loop). Then run the whole suite to confirm the fix didn't shift the flake elsewhere.

## Phase 5 — Report

Write `FLAKES.md`: per test — failure rate before, root-cause family, the experiment that proved it, the fix, runs-passed after. Plus a short "flake debt" section: patterns in the codebase likely to breed the same families again (a shared fixture, a real HTTP client in unit tests), so the next flake gets prevented rather than hunted.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tokyubevoxelverse](https://github.com/tokyubevoxelverse)
- **Source:** [tokyubevoxelverse/detox](https://github.com/tokyubevoxelverse/detox)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tokyubevoxelverse-detox-detox
- Seller: https://agentstack.voostack.com/s/tokyubevoxelverse
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.