hspec-junit-formatter

A JUnit XML runner/formatter for hspec.

Usage (with hspec-discover)

Place the following in test/SpecHook.hs:

import Test.Hspec
import Test.Hspec.JUnit.Config
import qualified Test.Hspec.JUnit.Formatter as Formatter

hook :: Spec -> Spec
hook = Formatter.use $ defaultJUnitConfig "test-suite"

This replaces the usual formatter, so only a JUnit report is generated and no other output is visible.

Registering instead of using

To make the JUnit formatter available for use with --format, but not used by default, use register:

hook2 :: Spec -> Spec
hook2 = Formatter.register $ defaultJUnitConfig "test-suite"

Adding a JUnit report

To produce a JUnit report in addition to normal output, use add:

hook3 :: Spec -> Spec
hook3 = Formatter.add $ defaultJUnitConfig "test-suite"

Environment Configuration

To configure things via @JUNIT_@-prefixed environment variables, import Formatter.Env instead. It exports all the same functions:

import qualified Test.Hspec.JUnit.Formatter.Env as FormatterEnv

And set the necessary variables,

JUNIT_OUTPUT_DIRECTORY=/tmp
JUNIT_SUITE_NAME=my-tests

hook4 :: Spec -> Spec
hook4 = FormatterEnv.add

Environment Enabling

To only apply a hook if JUNIT_ENABLED=1, wrap it in whenEnabled:

JUNIT_ENABLED=1

hook5 :: Spec -> Spec
hook5 = FormatterEnv.whenEnabled FormatterEnv.add

Without hspec-discover

Hooks are just functions of type Spec -> Spec, so you can apply them right before calling hspec in main:

main :: IO ()
main = hspec $ FormatterEnv.whenEnabled FormatterEnv.add spec

spec :: Spec
spec = describe "Addition" $ do
  it "adds" $ do
    2 + 2 `shouldBe` (4 :: Int)

Golden Testing

This project’s test suite uses [hspec-golden][] to generate an XML report for Example.hs and then compare that with golden XML files checked into the repository. If your work changes things in a functionally-correct way, but that diverges from the golden XML files, you need to regenerate them.

1. Run rm tests/golden*.xml
2. Run the specs again

We maintain specific golden XML files for GHC 8.x vs 9.x, so you will need to re-run the test suite with at least one of each series to regenerate all the necessary files.

Release

To trigger a release, merge a commit to main that follows Conventional Commits. In short,

• fix: to trigger a patch release
• feat: to trigger a minor release
• <type>!: or use a BREAKING CHANGE: footer to trigger a major release

We don’t enforce conventional commits generally (though you are free do so), it’s only required if you want to trigger release.

LICENSE