Skip to main content

testhunch

CI License: Apache-2.0

testhunch apprend de l'historique de votre CI quels tests un changement risque de casser, et les lance en premier.

Il lit les rapports JUnit XML que votre lanceur de tests produit déjà, ainsi que git diff, et n'est donc lié à aucun langage ni framework. Il est testé sur de vrais rapports de pytest, Vitest, Jest, Go (gotestsum), Java (Maven Surefire) et Rust (cargo-nextest).

Statut : pré-alpha. Le pipeline de données (ingestion, stockage, rapports sur les tests instables et en échec) et un classement de référence simple et explicable fonctionnent dès aujourd'hui. Le modèle appris et le benchmark public qui prouvera son efficacité sont prévus dans la feuille de route. Aucune promesse de précision n'est faite tant que ce benchmark n'existe pas.

Pourquoi

La CI lance tous les tests à chaque push, quoi qu'on ait modifié. Plus une suite grossit, plus cela veut dire de longues attentes, de grosses factures et des échecs aléatoires qui obligent à tout relancer.

Apprendre de l'historique des tests lesquels comptent pour un changement a fait ses preuves à grande échelle : chez Meta, Predictive Test Selection a divisé par deux le coût des tests tout en détectant plus de 99,9 % des changements défectueux. Mais aujourd'hui, on ne trouve cette capacité que sous ces formes :

Où la trouver Le problème
Systèmes internes de grandes entreprises Jamais publiés
Services commerciaux (Develocity, CloudBees Smart Tests, Datadog) Payants, souvent liés à un outil de build, et leurs promesses de précision sont invérifiables
Sélection basée sur Bazel Oblige à migrer tout le build vers Bazel
Plugins open source Un seul langage chacun, et surtout de l'analyse statique plutôt qu'un apprentissage sur l'historique

testhunch se veut la version ouverte et indépendante du langage, et veut prouver sa propre précision publiquement : chaque chiffre qu'il annonce est accompagné de la façon dont il a été mesuré, et un mode fantôme (shadow mode) enregistre ce qu'il aurait sauté, avant qu'on lui fasse confiance pour sauter quoi que ce soit.

Fonctionnement

flowchart LR
    CI["job de CI<br/>lance les tests"] -->|JUnit XML + git diff| Ingest
    subgraph testhunch
        Ingest["analyse et normalisation<br/>(tout framework)"] --> Store[("historique<br/>SQLite ou Postgres")]
        Store --> Report["rapport : tests instables,<br/>lents, en échec"]
        Store --> Rank["classement des tests<br/>pour un changement"]
    end
    Rank -->|liste ordonnée + raisons| CI
  1. Après votre job de tests, testhunch ingest enregistre le résultat de chaque test pour ce commit, ainsi que les fichiers modifiés.
  2. testhunch report affiche les tests instables (réussis et échoués sur le même commit, y compris quand une relance réussit dans la même exécution), les tests lents et les tests en échec.
  3. testhunch prioritize classe les tests selon les fichiers que vous avez modifiés, et explique pourquoi chacun arrive à cette place.

Démarrage rapide

# Dans un dépôt git, après avoir lancé vos tests avec une sortie JUnit :
uvx --from git+https://github.com/amazing-source/testhunch testhunch ingest junit.xml
uvx --from git+https://github.com/amazing-source/testhunch testhunch report
uvx --from git+https://github.com/amazing-source/testhunch testhunch prioritize --base origin/main

L'historique est conservé dans .testhunch/history.db (SQLite), sauf si vous indiquez une autre base avec --db ou TESTHUNCH_DATABASE_URL, par exemple postgresql://user@host/db.

Sortie réelle, obtenue avec deux exécutions de l'exemple pytest de tests/fixtures :

$ testhunch prioritize --changed src/sample/parametrized.py --limit 3
   1.  4.000  tests.test_sample::test_parametrized[2]  (matches changed file parametrized; failed in the latest run; failed 2 of 2 runs)
   2.  2.000  tests.test_sample::test_errors_in_setup  (failed in the latest run; failed 2 of 2 runs)
   3.  2.000  tests.test_sample::test_errors_in_teardown  (failed in the latest run; failed 2 of 2 runs)

Obtenir du JUnit XML depuis votre lanceur de tests

Lanceur Commande
pytest pytest --junitxml=junit.xml
Vitest vitest run --reporter=junit --outputFile=junit.xml
Jest jest --reporters=default --reporters=jest-junit (avec JEST_JUNIT_ADD_FILE_ATTRIBUTE=true)
Go gotestsum --junitfile junit.xml
Maven (Surefire) mvn test écrit un rapport par classe : testhunch ingest 'target/surefire-reports/TEST-*.xml'
cargo-nextest cargo nextest run --profile ci, avec [profile.ci.junit] dans .config/nextest.toml (rapport dans target/nextest/ci/junit.xml)

Dans GitHub Actions

- uses: actions/checkout@v7
  with:
    fetch-depth: 0 # testhunch a besoin de l'historique pour comparer avec la branche de base
- run: pytest --junitxml=junit.xml
- if: ${{ !cancelled() }}
  run: uvx --from git+https://github.com/amazing-source/testhunch testhunch ingest junit.xml --base origin/main

Un fichier SQLite local ne survit pas d'une exécution de CI à l'autre. Pour un vrai usage en CI, faites pointer TESTHUNCH_DATABASE_URL vers Postgres, ou envoyez les rapports à une API auto-hébergée (ci-dessous).

Héberger l'API soi-même

docker compose up --build        # Postgres, les migrations, puis l'API sur :8000
curl http://localhost:8000/readyz
Endpoint Rôle
POST /v1/runs Envoyer des rapports : fichiers reports en multipart et JSON metadata (repo, commit_sha, et en option branch, base_sha, changes)
GET /v1/report?repo=owner/name Tests instables, les plus lents et en échec
POST /v1/prioritize Tests classés pour repo et changed_paths
GET /healthz, GET /readyz Vivacité, et disponibilité (base de données comprise)

Définissez TESTHUNCH_API_TOKEN pour exiger Authorization: Bearer <token> sur /v1. Sans jeton, l'API est ouverte, ce qui n'est acceptable que sur votre propre machine.

Développement

uv sync --all-extras
uv run pytest                       # tests de contrat sur SQLite ; ceux sur Postgres sont ignorés
uv run ruff check . && uv run ruff format --check . && uv run mypy

# Lancer aussi les tests de contrat du stockage sur Postgres :
docker compose up -d postgres
TESTHUNCH_TEST_POSTGRES_URL=postgresql://testhunch:testhunch@127.0.0.1:5432/testhunch uv run pytest

Utilisez 127.0.0.1 et non localhost : Compose ne publie le port qu'en IPv4, et sous Windows localhost essaie d'abord ::1, où chaque connexion reste bloquée jusqu'à expiration du délai.

Les décisions de conception sont consignées dans docs/adr. La couche de stockage est une seule implémentation SQL, exécutée sur SQLite comme sur Postgres, et chaque test de stockage tourne sur les deux.

Licence

Apache-2.0

Metadata

Release files for testhunch 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for testhunch 0.1.0
File Size Uploaded Provenance Actions
testhunch-0.1.0.tar.gz 26.1 kB With provenance Details for testhunch-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for testhunch 0.1.0
File Interpreter ABI Platform Actions
testhunch-0.1.0-py3-none-any.whl Python 3 none any Details for testhunch-0.1.0-py3-none-any.whl

Total release size: 59.8 kB

Release files / testhunch-0.1.0.tar.gz

Download URL testhunch-0.1.0.tar.gz
Size 26.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e29ab2195c82c196cca6100b58189b45c3cba0eac4be5f7c2f62ea5ac9e0353a
BLAKE2b-256 checksum
How to use checksums
e478254e63b682a1c6b5a456499cc81360f6e8a5f420434f1f75837889243cff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.

Transparency log

Release files / testhunch-0.1.0-py3-none-any.whl

Download URL testhunch-0.1.0-py3-none-any.whl
Size 33.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8dd468eae03d541036d3f2acc00c5e220044ed7287d1866ebd80988feac07aa5
BLAKE2b-256 checksum
How to use checksums
b52dd70d9c22cb0ebeb5c67a83eb630cb3f723f964db999e9e1ab0540e7e42a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.

Transparency log

Security for testhunch 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for testhunch-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page