gapix

Your tests pass. But are they actually good?

Most coverage tools tell you what is tested. gapix tells you how well.

Getting Started · Features · Test Quality · AI Providers · CLI · Contributing

The Problem

You have 80%+ code coverage. CI is green. But bugs still make it to production.

Why? Because tests like this technically "cover" your code:

// ❌ This passes but catches nothing
test('should process user', async () => {
  const result = await processUser(mockData);
  expect(result).toBeTruthy();
});

// ❌ E2E test that clicks through a flow but never checks outcomes
test('signup flow', async ({ page }) => {
  await page.goto('/signup');
  await page.fill('#email', '[email protected]');
  await page.click('button[type="submit"]');
  await page.waitForURL('/dashboard');
  // ...no assertions on what actually happened
});

Coverage tools can't catch this. gapix can.

🚀 Getting Started

# Install globally (recommended)
npm install -g @artshllaku/gapix

# Run analysis with interactive HTML report
gapix analyze ./src -o html

Or run without installing:

npx --package=@artshllaku/gapix gapix analyze ./src -o html

That's it — an interactive report opens in your browser.

✨ Features

Works with any testing framework

gapix analyzes the AST of your test files — it works with any framework that uses standard test patterns:

| Framework | Status | Matchers | |-----------|--------|----------| | Jest | ✅ Full | All 50+ matchers recognized | | Vitest | ✅ Full | Same API as Jest | | Playwright | ✅ Full | toBeVisible, toHaveURL, toHaveText, toHaveScreenshot, etc. | | Testing Library | ✅ Full | toBeInTheDocument, toHaveTextContent, toHaveAttribute, etc. | | Cypress | ✅ Partial | expect() chains detected | | Mocha + Chai | ✅ Partial | describe/it + expect() style |

What gapix does

Source Files (.ts/.tsx)            Test Files (.test.ts, .spec.ts)
       │                                    │
   AST Parse                           AST Parse
       │                                    │
  Extract:                             Extract:
  · functions & classes                · describe/it/test blocks
  · exports & complexity               · assertions per test case
  · parameters & return types          · matcher types & targets
       │                                    │
       └──────── Coverage Mapping ──────────┘
                      │
               Risk Assessment
                      │
           ┌──────────┴──────────┐
           │                     │
    AI Gap Analysis    Test Quality Scoring
           │                     │
           └──────────┬──────────┘
                      │
          Interactive HTML Report

Interactive HTML report

Dark-themed, self-contained HTML dashboard — auto-opens in your browser:

• Summary dashboard — files analyzed, coverage %, tested/untested counts
• Quality grades — each test file scored 0-100 with letter grades
• File-level breakdown — colored progress bars, click to expand details
• Function-level detail — every function/method with tested/untested status
• AI suggestions — specific, runnable test code you can copy-paste

🔍 Test Quality Analysis

This is what makes gapix different. Instead of counting lines, it evaluates what your tests actually check:

| Finding | Severity | What it means | |---------|----------|---------------| | No assertions | 🔴 High | Test runs code but never calls expect() | | Weak matchers | 🟡 Medium | toBeTruthy() / toBeDefined() instead of checking real values | | Single assertion | 🟡 Medium | Only one check in a test — probably not enough | | Missing edge cases | 🟡 Medium | No tests for null, empty, or error inputs | | Missing error handling | 🔴 High | Source has try/catch but no test triggers it | | Wrong assertion target | 🟡 Medium | Asserting on a side effect, not the core behavior |

Quality scoring

| Score | Grade | What it means | |-------|-------|---------------| | 85–100 | Excellent | Strong, specific assertions that catch real bugs | | 65–84 | Good | Solid tests, minor improvements possible | | 40–64 | Fair | Tests exist but have gaps — false confidence risk | | 0–39 | Poor | Tests provide little value — likely false coverage |

🤖 AI Providers

gapix works without AI using rule-based AST analysis. Add an AI provider for deeper, context-aware insights:

# OpenAI (recommended for best results)
gapix set-provider openai
gapix set-key YOUR_OPENAI_API_KEY

# Ollama (free, runs locally)
ollama pull llama3
gapix set-provider ollama

# Check your config
gapix show-config

| Mode | What you get | |------|-------------| | Without AI | Structural analysis — no assertions, weak matchers, single checks | | With AI | Deep analysis — missing edge cases, wrong targets, context-specific suggestions with runnable code |

📖 CLI Reference

# Analyze a project
gapix analyze <path> [options]

# Options
  -o, --output <format>      json | markdown | html (default: json)
  -d, --output-dir <dir>     Output directory (default: .)
  -p, --pattern <patterns>   Glob patterns to include
  -e, --exclude <patterns>   Glob patterns to exclude
  --skip-quality             Skip test quality analysis

# Other commands
gapix show-report            Re-open the last HTML report
gapix set-provider <name>    Set AI provider (openai | ollama)
gapix set-key <key>          Set API key
gapix show-config            Show current config

Output formats

| Format | Use case | |--------|----------| | HTML | Interactive dashboard, share with your team | | JSON | CI/CD pipelines, custom tooling | | Markdown | Pull request comments, wiki pages |

🛠 Development

git clone https://github.com/artshllk/gapix.git
cd gapix
npm install
npm run build
npm test

See docs/testing-guide.md for a detailed walkthrough.

🤝 Contributing

Contributions are welcome.

1. Fork the repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and add tests
4. Run npm test
5. Open a Pull Request

Found a bug? Have an idea?

Open an issue

MIT License · Built by Art Shllaku