Accelerate your Flutter test suite with lightning speed! ⚡

Sample : 4600 tests running in ~1 min...

📝 Features

• Dramatically speeds up test execution: By bundling tests into a single file, testRocket significantly reduces the overall runtime of your test suite.
• Simplifies test organization: Automatically collects and consolidates tests from across your project, eliminating the need for manual test management.
• Test reporting: Generate test reports & author trends in .testRocket directory and interact in a html report.
• Interactive coverage visualization: Quickly see code coverage trends and test performance over time.
• User-friendly command-line interface: Interact with the tool using intuitive commands designed for clarity and ease of use.

📥 Installation

Activate the testRocket command-line tool globally:

dart pub global activate test_rocket

🪝 Automated Pre-Commit Hook

To continuously track test runs across your team and catch regressions before committing, add testRocket run to your git pre-commit hook:

Create or update .git/hooks/pre-commit (or your custom git-hook file) with the following content:

#!/bin/sh
set -e

# Run tests with coverage
testRocket run --coverage
# Stage updated report and gitattributes with this commit
git add .testRocket/report.csv .gitattributes

⚙️ Configuration (pubspec.yaml)

You can configure default settings for your project directly in its pubspec.yaml:

# pubspec.yaml
test_rocket:
  min_coverage: 80 # Sets the minimum/target coverage percentage (e.g. 80 or 80.0)

Usage

👨‍💻 Core Commands

• testRocket run: Executes the bundled tests and automatically appends results to .testRocket/report.csv.
  • --coverage: Runs tests with code coverage collection.
  • --fail-on-drop: Fails with exit code 1 if code coverage drops compared to the previous recorded run in report.csv.
• testRocket trends: Visualizes test and coverage trends over time as an interactive terminal graph and automatically opens .testRocket/trends.html in your default browser.

📈 Test reporting & Trends

Test reporting is built to analyze testing performance and code coverage trends across your team. Every test run automatically logs metrics to .testRocket/report.csv.

To track code coverage in the report, simply pass --coverage:

testRocket run --coverage

To visualize testing health and coverage trajectory over time:

testRocket trends

This generates a rich, interactive HTML dashboard (.testRocket/trends.html) with zoom/pan controls, range presets, and paginated run history, automatically opening it in your browser (along with a terminal ASCII preview).

🌳 Version Control Support

🤝 Automatic Merge & Rebase Conflict Resolution

When multiple authors push test runs, pulling or rebasing can cause Git conflicts on .testRocket/report.csv. testRocket automatically solves this by ensuring .gitattributes uses Git's built-in union merge driver:

.testRocket/report.csv merge=union

With merge=union, Git automatically unites rows from incoming and local runs during git pull and git rebase without stopping for manual conflict resolution. testRocket automatically configures this in your project on testRocket run.

Tip: If .testRocket/ is in your .gitignore, un-ignore report.csv so the history is shared with your team:

.testRocket/*
!.testRocket/report.csv

🤔 Some tests are failing. Why?!

Test failure with testRocket expose vulnerabilities in the test suite. If tests are passing with the regular flutter run but fail in the testRocket run, then there is a good chance the tests are not truly isolated. Hence, the tests might be sharing some resource in the test environment, eg; a shared service locator, a ViewBinding, etc.

💉 Diagnose with testRocket doctor (Experimental)

⚠️ testRocket doctor is currently experimental! We are working to make this accurate.

Instead of bisecting by hand, run:

testRocket doctor

Doctor will:

1. Run the full bundle and collect failing files.
2. Re-run each failing file alone — separating real bugs from isolation issues.
3. Bisect the predecessor files to pinpoint the culprit that triggers the failure when run before the victim.
4. Scan the culprit for common leak patterns (GetIt without reset, top-level TestWidgetsFlutterBinding.ensureInitialized(), HttpOverrides.global, etc.) and suggest fixes.

A full report is written to .testRocket/doctor.md. Useful flags:

• --suspect <path> — skip the baseline run and diagnose a specific file.
• --max-victims <n> — cap how many files to bisect (default 5).
• --json — also emit .testRocket/doctor.json for tooling.

Exit codes: 0 no failures, 1 isolation issue, 2 real bug, 3 doctor could not diagnose (compile error or runner crash).

☕ Show your support