Repository navigation
Expand file tree
/
Copy pathREADME.lhs
More file actions
142 lines (100 loc) · 3.93 KB
/
Copy pathREADME.lhs
File metadata and controls
142 lines (100 loc) · 3.93 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
# hspec-junit-formatter
[](https://hackage.haskell.org/package/hspec-junit-formatter)
[](http://stackage.org/nightly/package/hspec-junit-formatter)
[](http://stackage.org/lts/package/hspec-junit-formatter)
[](https://github.com/freckle/hspec-junit-formatter/actions/workflows/ci.yml)
A `JUnit` XML runner/formatter for [`hspec`](http://hspec.github.io/).
<!--
```haskell
{-# OPTIONS_GHC -Wno-unused-top-binds #-}
module Main (main) where
import Prelude
-- Used in a later example
import qualified Test.Hspec.JUnit.Formatter.Env as FormatterEnv
```
-->
## Usage (with `hspec-discover`)
Place the following in `test/SpecHook.hs`:
```haskell
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`:
```haskell
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`:
```haskell
hook3 :: Spec -> Spec
hook3 = Formatter.add $ defaultJUnitConfig "test-suite"
```
### Mixing Formatters
In addition to the formatter named `junit`, this library also registers
formatters named `{formatter}+junit` for every existing formatter. This allows
doing something like `--format progress+junit` to produce output with `progress`
while also producing a JUnit file though `junit`.
The `add` hook can be thought of like `--format checks+junit`, so this extra
registration allows for similar "add" behavior on top of non-default formatters.
Once registered, they can be seen in Hspec's `--help`:
```console
-f NAME --format=NAME use a custom formatter; this can be one of
junit, checks+junit, specdoc+junit,
progress+junit, failed-examples+junit,
silent+junit, checks, specdoc, progress,
failed-examples or silent
```
### Environment Configuration
To configure things via @JUNIT_@-prefixed environment variables, import
`Formatter.Env` instead. It exports all the same functions:
```hs
import qualified Test.Hspec.JUnit.Formatter.Env as FormatterEnv
```
And set the necessary variables,
```
JUNIT_OUTPUT_DIRECTORY=/tmp
JUNIT_SUITE_NAME=my-tests
```
```haskell
hook4 :: Spec -> Spec
hook4 = FormatterEnv.add
```
### Environment Enabling
To only apply a hook if `JUNIT_ENABLED=1`, wrap it in `whenEnabled`:
```
JUNIT_ENABLED=1
```
```haskell
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`:
```haskell
main :: IO ()
main = hspec $ FormatterEnv.register spec -- or use, or add
spec :: Spec
spec = describe "Addition" $ do
it "adds" $ do
2 + 2 `shouldBe` (4 :: Int)
```
## 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.
[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/#summary
---
[LICENSE](./LICENSE)