Haruspex Documentation

How does Haruspex work?

Haruspex provides you with a free-form query interface for your CI data, and it does so by processing a relatively standard file across languages: JUnit XML. Initially produced by Java's JUnit test framework, early CI systems like Hudson, Jenkins and Bamboo started parsing these files in order to gain more transparency over whether or not, for example, the CI run had suceeded, failed because the tests failed, or failed because of technical issues.

Haruspex follows a similar approach, but we don't view each CI run as being independent. The accurate picture of the health of your CI system comes from aggregating and viewing trends over time, not from individual runs.

Getting Started With Your CI Pipelines.

Generating JUnit Files

First, we need to set up the generation of JUnit files by your test framework. Here's some useful links and guidelines for some of the most common languages:

• Bazel
• Java
• JavaScript
• Python
• Ruby
• Scala
• Swift

Regardardless of what langauge you are using, once your setup is producing JUnit files, you're ready to continue in this guide.

Uploading to Haruspex

In this guide we assume that your setup produces one JUnit file per CI run, but for example, in Java/JUnit it is one Junit file per test class. You will need to upload each file in order to gain a complete picture.

To do this, add another step to your CI script:

curl -X POST \
    --data-binary @report.xml \
    -H "Content-Type: application/xml" \
    -H "Authorization: $HARUSPEX_DATASET_SECRET" \
    https://ui.haruspex.dev/api/$DATASET_NAME/junit

This will now upload your test results to Haruspex on every CI invocation, and allows you to get to the bottom of what is eating your CI performance.

Using Haruspex

Trigger a CI run with the repository you modified, then go to the Haruspex user interface, and start exploring your test data.