{"id":50826552,"url":"https://github.com/callstackincubator/overlapped","last_synced_at":"2026-06-13T19:35:27.592Z","repository":{"id":360512156,"uuid":"1250500267","full_name":"callstackincubator/overlapped","owner":"callstackincubator","description":"Find the unit tests that overlap with integration tests and remove them","archived":false,"fork":false,"pushed_at":"2026-06-01T14:35:54.000Z","size":100,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T19:35:12.649Z","etag":null,"topics":["ai-agents","coverage","duplication","integration-testing","jest","overlap","testing","unit-testing","vitest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/callstackincubator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-26T17:37:25.000Z","updated_at":"2026-06-06T22:19:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/callstackincubator/overlapped","commit_stats":null,"previous_names":["callstackincubator/overlapped"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/callstackincubator/overlapped","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Foverlapped","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Foverlapped/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Foverlapped/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Foverlapped/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/callstackincubator","download_url":"https://codeload.github.com/callstackincubator/overlapped/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Foverlapped/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34298247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","coverage","duplication","integration-testing","jest","overlap","testing","unit-testing","vitest"],"created_at":"2026-06-13T19:35:26.952Z","updated_at":"2026-06-13T19:35:27.585Z","avatar_url":"https://github.com/callstackincubator.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# overlapped\n\nFind the unit tests your AI agent wrote twice.\n\n`overlapped` detects unit tests that exercise code already covered by your baseline suite, usually integration, e2e, or provider tests. It runs each candidate test in isolation, compares its statement and branch coverage against the baseline, and reports tests that may be safe to remove.\n\nUse it when AI-assisted test generation has inflated your suite and you want to keep the tests that still protect real behavior.\n\n- Detects fully overlapped unit tests\n- Compares against Istanbul `coverage-final.json`\n- Supports Vitest and Jest\n- Auto-detects your runner from project dependencies\n- Generates a reviewable JSON report\n- Can preview and apply removals\n\n`overlapped` treats results as a cleanup queue, not a delete command. Some tests with overlapped or empty coverage still protect contracts such as exports, config shape, generated files, or release metadata.\n\n## Quick Start\n\nSplit your test scripts into baseline and unit suites:\n\n```json\n{\n  \"scripts\": {\n    \"test:unit\": \"vitest run src\",\n    \"test:integration\": \"vitest run test/integration\"\n  }\n}\n```\n\nRun the analyzer:\n\n```bash\nnpx overlapped analyze\n```\n\nExample output:\n\n```text\n=== overlapped ===\n\nTotal tests analyzed: 312\n100% overlapped candidates: 27\nTests with unique coverage: 285\n\nFiles where every test is a removal candidate (2):\n  src/__tests__/legacy-client.test.ts\n  src/utils/__tests__/formatters.test.ts\n\nFiles with removal candidates (6):\n  src/__tests__/client.test.ts: 5 candidates, 12 with unique coverage\n  src/core/__tests__/validation.test.ts: 3 candidates, 9 with unique coverage\n\nReport written to overlapped-report.json\n```\n\nReview the report:\n\n```bash\ncat overlapped-report.json\n```\n\nPreview the cleanup:\n\n```bash\nnpx overlapped prune --dry-run\n```\n\nApply removals when the preview looks right:\n\n```bash\nnpx overlapped prune\n```\n\nThen run your full test suite with coverage and confirm thresholds still pass.\n\n## What It Catches\n\nAI agents are good at producing tests that look useful. They are also good at repeating coverage you already have.\n\n`overlapped` finds tests whose covered statements and branches are already covered by your baseline suite. That makes it useful when:\n\n- Unit test files have grown after AI-assisted generation\n- CI time is increasing without better coverage\n- Integration or provider tests already exercise the same behavior\n- You want a safer review queue before deleting test code\n- You need evidence before pruning a large suite\n\nFor example, `agent-device` used `overlapped` to [drop 151 unnecessary unit tests](https://github.com/callstackincubator/agent-device/pull/595) without losing coverage.\n\n## How It Works\n\n```mermaid\nflowchart TD\n  A[Baseline suite] --\u003e B[coverage-final.json]\n  C[Candidate unit tests] --\u003e D[Run each test alone with coverage]\n  D --\u003e E[Per-test coverage fingerprint]\n  B --\u003e F[Compare fingerprints]\n  E --\u003e F\n  F --\u003e G{Fully covered by baseline?}\n  G --\u003e|Yes| H[Removal candidate]\n  G --\u003e|No| I[Keep: unique coverage]\n  H --\u003e J[overlapped-report.json]\n  I --\u003e J\n```\n\n`overlapped`:\n\n1. Runs or loads Istanbul `coverage-final.json` for your baseline suite.\n2. Runs each candidate unit test in isolation with coverage.\n3. Converts covered statements and branches into fingerprint keys, such as `\"/src/foo.ts:s:3\"` and `\"/src/foo.ts:b:1:0\"`.\n4. Marks a test as a removal candidate only when every key in its fingerprint already exists in the baseline fingerprint.\n5. Removes candidate test blocks with bracket matching when you run `prune`.\n\nNo AST dependency is required for pruning.\n\n## Prerequisites\n\n- Node.js `\u003e= 22`\n- Vitest or Jest installed in your project\n- Istanbul-compatible coverage output\n- For Vitest, a configured coverage provider such as `@vitest/coverage-v8`\n- For Vitest, `vitest` and `@vitest/coverage-v8` on the same major version\n- A baseline suite such as integration, e2e, provider tests, or an existing `coverage-final.json`\n\n## Usage\n\n### `overlapped analyze`\n\nBuilds the overlap report.\n\nA baseline is required. Use one of:\n\n- `test:integration`\n- `--reference`\n- `--reference-command`\n- `--reference-coverage`\n\nRecommended setup:\n\n```json\n{\n  \"scripts\": {\n    \"test:unit\": \"vitest run src\",\n    \"test:integration\": \"vitest run test/integration\"\n  }\n}\n```\n\nThen run:\n\n```bash\nnpx overlapped analyze\n```\n\nWith this setup, `overlapped` adds coverage flags to `test:integration` and infers candidate unit tests from `test:unit`.\n\nSimilar-looking scripts such as `test-integration`, `test:e2e`, or `test:provider` are not guessed. Use the `test:integration` convention for zero-config baseline coverage, or pass `--reference-command`.\n\n### Named Vitest or Jest projects\n\n```bash\nnpx overlapped analyze \\\n  --reference integration \\\n  --unit unit\n```\n\n### Existing baseline coverage\n\n```bash\nnpx overlapped analyze \\\n  --reference-coverage ./coverage/coverage-final.json\n```\n\n### Custom baseline command\n\n```bash\nnpx overlapped analyze \\\n  --reference-command \"pnpm test:integration:coverage\"\n```\n\nThe command must produce Istanbul `coverage-final.json`, either at `coverage/coverage-final.json` or at the path passed with `--reference-coverage`.\n\nIf your script writes coverage to a fixed path:\n\n```bash\nnpx overlapped analyze \\\n  --reference-command \"npm run test:coverage\" \\\n  --reference-coverage ./coverage/integration/coverage-final.json\n```\n\n### Custom unit test layout\n\n```bash\nnpx overlapped analyze \\\n  --include \"packages/*/src/**/*.test.ts\" \\\n  --exclude \"packages/*/src/**/*.integration.test.ts\"\n```\n\n### Command Flow\n\n- Baseline coverage comes from `test:integration`, `--reference`, `--reference-command`, or `--reference-coverage`.\n- Candidate scope comes from `test:unit`, `--unit`, `--include`, or default Jest/Vitest test file patterns.\n- Candidate tests are checked through the local Vitest or Jest binary, one file and one test name at a time.\n- Runner binaries are resolved from the current package or a parent workspace `node_modules/.bin/`.\n\n## Pruning Tests\n\n### `overlapped prune`\n\nReads `overlapped-report.json` and removes reported overlap candidates.\n\nFiles where every test is a candidate are deleted entirely. Mixed files have individual test blocks removed.\n\nAlways preview first:\n\n```bash\nnpx overlapped prune --dry-run\n```\n\nApply removals:\n\n```bash\nnpx overlapped prune\n```\n\nAfter pruning, run your full suite with coverage before committing.\n\n## Options\n\n| Option | Description | Default |\n|---|---|---|\n| `--runner \u003cvitest\\|jest\u003e` | Test runner | auto-detected |\n| `--reference \u003cname\u003e` | Reference suite project name | - |\n| `--reference-command \u003ccommand\u003e` | Command that generates reference coverage | - |\n| `--reference-coverage \u003cpath\u003e` | Path to existing `coverage-final.json` | - |\n| `--unit \u003cname\u003e` | Unit test suite project name | inferred from `test:unit`, otherwise - |\n| `--include \u003cglob\u003e` | Unit test file pattern, repeatable | inferred from `test:unit`, otherwise Jest/Vitest-style `*.test.*` and `*.spec.*` files |\n| `--exclude \u003cglob\u003e` | Unit test file pattern to exclude | common `.integration.*` and `.e2e.*` patterns |\n| `--concurrency \u003cn\u003e` | Parallel test runs | `8` |\n| `--report \u003cpath\u003e` | Report output path | `overlapped-report.json` |\n| `--dry-run` | Preview prune without modifying files | `false` |\n\n## License\n\nMIT\n\n## Made at Callstack\n\n`overlapped` is an open source project and will always remain free to use. It was developed by [Callstack](https://callstack.com/), the team helping companies ship cross-platform products at AI speed.\n\nCallstack is part of the React Foundation, a long-time contributor to React Native, and helps teams build, modernize, and scale production cross-platform products, including agentic software development at scale.\n\nNeed help turning AI-assisted delivery into production software? [Book a consultation](https://callstack.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcallstackincubator%2Foverlapped","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcallstackincubator%2Foverlapped","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcallstackincubator%2Foverlapped/lists"}