lawspec 0.17.2 → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +137 -0
- package/README.md +3 -3
- package/bin/lawspec.mjs +146 -10
- package/build.json +86 -68
- package/core.wasm +0 -0
- package/doctor.mjs +6 -1
- package/examples/specs/domain_modeling.lawspec +20 -3
- package/examples/specs/durations.lawspec +63 -0
- package/examples/specs/keywords.lawspec +33 -0
- package/examples/specs/limits.lawspec +43 -0
- package/examples/specs/railway.lawspec +78 -0
- package/examples/specs/resilience.lawspec +245 -0
- package/examples/specs/workflows.lawspec +145 -0
- package/index.d.ts +1 -0
- package/package.json +1 -1
- package/templates.mjs +2 -2
- package/test-command.mjs +205 -0
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
unit example.resilience
|
|
2
|
+
|
|
3
|
+
import lawspec.resilience as r
|
|
4
|
+
import example.limits as limits
|
|
5
|
+
|
|
6
|
+
-- Conformance of each target's workflow runtime with a reference model.
|
|
7
|
+
-- The adapters call the runtime; the checked definitions are the reference.
|
|
8
|
+
-- Delays are whole microseconds.
|
|
9
|
+
|
|
10
|
+
-- The delay before attempt k (2 or more) of each retry strategy.
|
|
11
|
+
definition exponentialDelay (base :: Integer where base >= 0 && base <= 1000000)
|
|
12
|
+
(factor :: Integer where factor >= 1 && factor <= 4)
|
|
13
|
+
(attempt :: Integer where attempt >= 2 && attempt <= 10) :: Integer is
|
|
14
|
+
base * prelude.pow factor (attempt - 2)
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
definition linearDelay (base :: Integer where base >= 0 && base <= 1000000)
|
|
18
|
+
(step :: Integer where step >= 0 && step <= 1000000)
|
|
19
|
+
(attempt :: Integer where attempt >= 2 && attempt <= 10) :: Integer is
|
|
20
|
+
base + step * (attempt - 2)
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
runtimeExponentialDelay :: Integer -> Integer -> Integer -> Integer
|
|
24
|
+
runtimeLinearDelay :: Integer -> Integer -> Integer -> Integer
|
|
25
|
+
runtimeFibonacciDelay :: Integer -> Integer -> Integer
|
|
26
|
+
|
|
27
|
+
-- The first outputs of SplitMix64 for a seed, and full jitter.
|
|
28
|
+
splitMix :: UInt64 -> Int32 -> List UInt64
|
|
29
|
+
fullJitter :: UInt64 -> Integer -> Integer
|
|
30
|
+
|
|
31
|
+
-- A stage that always fails, retried exponentially from 100ms, doubling, for
|
|
32
|
+
-- the given number of attempts: the waits the runtime makes.
|
|
33
|
+
retriedWaits :: Int32 -> List Integer
|
|
34
|
+
|
|
35
|
+
-- The same, with a when predicate that rejects the error: no waits.
|
|
36
|
+
rejectedWaits :: Int32 -> List Integer
|
|
37
|
+
|
|
38
|
+
-- Unrefined inputs are mapped into range, so every target generates them
|
|
39
|
+
-- directly: a base up to 65535us, a factor of 1 to 4, and attempts 2 to 10.
|
|
40
|
+
law `exponential delays match the reference` is
|
|
41
|
+
definition is
|
|
42
|
+
`for all` (base :: UInt16) (f :: UInt8) (a :: UInt8) .
|
|
43
|
+
runtimeExponentialDelay (prelude.Integer base) (1 + prelude.rem (prelude.Integer f) 4) (2 + prelude.rem (prelude.Integer a) 9) =
|
|
44
|
+
exponentialDelay (prelude.Integer base) (1 + prelude.rem (prelude.Integer f) 4) (2 + prelude.rem (prelude.Integer a) 9)
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
law `the fifth exponential attempt` is
|
|
49
|
+
definition is
|
|
50
|
+
`for all` (base :: Integer where base == 100000) . runtimeExponentialDelay base 2 5 = 800000
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
law `linear delays match the reference` is
|
|
55
|
+
definition is
|
|
56
|
+
`for all` (base :: UInt16) (step :: UInt16) (a :: UInt8) .
|
|
57
|
+
runtimeLinearDelay (prelude.Integer base) (prelude.Integer step) (2 + prelude.rem (prelude.Integer a) 9) =
|
|
58
|
+
linearDelay (prelude.Integer base) (prelude.Integer step) (2 + prelude.rem (prelude.Integer a) 9)
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
law `fibonacci delays add the two before` is
|
|
63
|
+
definition is
|
|
64
|
+
`for all` (base :: UInt16) (a :: UInt8) .
|
|
65
|
+
runtimeFibonacciDelay (prelude.Integer base) (4 + prelude.rem (prelude.Integer a) 27) =
|
|
66
|
+
runtimeFibonacciDelay (prelude.Integer base) (3 + prelude.rem (prelude.Integer a) 27) +
|
|
67
|
+
runtimeFibonacciDelay (prelude.Integer base) (2 + prelude.rem (prelude.Integer a) 27)
|
|
68
|
+
end
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
law `fibonacci delays start at the base` is
|
|
72
|
+
definition is
|
|
73
|
+
`for all` (base :: UInt16) .
|
|
74
|
+
runtimeFibonacciDelay (prelude.Integer base) 2 = prelude.Integer base and
|
|
75
|
+
runtimeFibonacciDelay (prelude.Integer base) 3 = prelude.Integer base
|
|
76
|
+
end
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
law `SplitMix64 is the same everywhere` is
|
|
80
|
+
definition is
|
|
81
|
+
`for all` (count :: Int8 where count >= 0 && count <= 3) .
|
|
82
|
+
prelude.length (splitMix 0 (prelude.Int32 count)) = prelude.Integer count
|
|
83
|
+
end
|
|
84
|
+
example `seed zero` is
|
|
85
|
+
count = 3
|
|
86
|
+
expect splitMix 0 (prelude.Int32 count) = [16294208416658607535, 7960286522194355700, 487617019471545679]
|
|
87
|
+
end
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
law `full jitter stays within the delay` is
|
|
91
|
+
definition is
|
|
92
|
+
`for all` (seed :: UInt64) (delay :: UInt32) .
|
|
93
|
+
(fullJitter seed (prelude.Integer delay) >= 0 && fullJitter seed (prelude.Integer delay) <= prelude.Integer delay) = true
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
law `a failing stage waits between its attempts` is
|
|
98
|
+
definition is
|
|
99
|
+
`for all` (attempts :: Int8 where attempts >= 1 && attempts <= 6) .
|
|
100
|
+
prelude.length (retriedWaits (prelude.Int32 attempts)) = prelude.Integer attempts - 1
|
|
101
|
+
end
|
|
102
|
+
example `four attempts` is
|
|
103
|
+
attempts = 4
|
|
104
|
+
expect retriedWaits (prelude.Int32 attempts) = [100000, 200000, 400000]
|
|
105
|
+
end
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
law `a rejected error is not retried` is
|
|
109
|
+
definition is
|
|
110
|
+
`for all` (attempts :: Int8 where attempts >= 1 && attempts <= 6) .
|
|
111
|
+
rejectedWaits (prelude.Int32 attempts) = []
|
|
112
|
+
end
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
-- Calls limited at each time (microseconds, in order) under one runtime
|
|
116
|
+
-- with its gates on: whether each call was admitted.
|
|
117
|
+
limitedAt :: List Integer -> List Bool
|
|
118
|
+
|
|
119
|
+
definition admits (gate :: r.Gate) :: Bool is
|
|
120
|
+
match gate with
|
|
121
|
+
| Admit -> true
|
|
122
|
+
| WaitFor micros -> false
|
|
123
|
+
| Reject -> false
|
|
124
|
+
end
|
|
125
|
+
end
|
|
126
|
+
|
|
127
|
+
-- The reference: the resilience unit's token bucket, folded over the times.
|
|
128
|
+
definition bucketRun (state :: r.TokenBucket) (times :: List Integer) :: List Bool is
|
|
129
|
+
match times with
|
|
130
|
+
| Nil -> Nil
|
|
131
|
+
| Cons t rest ->
|
|
132
|
+
match r.tokenBucketAdmit 2 1000000 state t with
|
|
133
|
+
| Step next gate -> Cons (admits gate) (bucketRun next rest)
|
|
134
|
+
end
|
|
135
|
+
end
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
-- Times a millisecond apart and more, as a list of gaps.
|
|
139
|
+
definition timesFrom (start :: Integer) (gaps :: List UInt16) :: List Integer is
|
|
140
|
+
match gaps with
|
|
141
|
+
| Nil -> Nil
|
|
142
|
+
| Cons gap rest -> Cons start (timesFrom (start + prelude.Integer gap * 1000) rest)
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
law `the rate limit admits as the token bucket does` is
|
|
147
|
+
definition is
|
|
148
|
+
`for all` (gaps :: List UInt16) .
|
|
149
|
+
limitedAt (timesFrom 0 gaps) = bucketRun (r.tokenBucketStart 2 1000000 0) (timesFrom 0 gaps)
|
|
150
|
+
end
|
|
151
|
+
example `three calls at once` is
|
|
152
|
+
gaps = [0, 0, 0]
|
|
153
|
+
expect limitedAt (timesFrom 0 gaps) = [true, true, false]
|
|
154
|
+
end
|
|
155
|
+
end
|
|
156
|
+
|
|
157
|
+
-- The other state machines, which every target runs as generated code.
|
|
158
|
+
law `an open breaker rejects until its cooldown ends` is
|
|
159
|
+
definition is
|
|
160
|
+
`for all` (t :: UInt16) .
|
|
161
|
+
r.breakerAdmit (r.Open 1000) (prelude.Integer t) =
|
|
162
|
+
prelude.select (prelude.Integer t >= 1000) (r.Step r.HalfOpen r.Admit) (r.Step (r.Open 1000) r.Reject)
|
|
163
|
+
end
|
|
164
|
+
end
|
|
165
|
+
|
|
166
|
+
law `a breaker opens after enough failures in its window` is
|
|
167
|
+
definition is
|
|
168
|
+
`for all` (gap :: UInt8) .
|
|
169
|
+
r.breakerRecord 2 1000 500 (r.breakerRecord 2 1000 500 (r.Closed []) 10 false) (10 + prelude.Integer gap) false =
|
|
170
|
+
r.Open (510 + prelude.Integer gap)
|
|
171
|
+
end
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
law `a breaker forgets failures outside its window` is
|
|
175
|
+
definition is
|
|
176
|
+
`for all` (gap :: UInt8) .
|
|
177
|
+
r.breakerRecord 2 100 500 (r.breakerRecord 2 100 500 (r.Closed []) 0 false) (200 + prelude.Integer gap) false =
|
|
178
|
+
r.Closed [200 + prelude.Integer gap]
|
|
179
|
+
end
|
|
180
|
+
end
|
|
181
|
+
|
|
182
|
+
law `a successful trial closes the breaker` is
|
|
183
|
+
definition is
|
|
184
|
+
`for all` (t :: UInt16) . r.breakerRecord 2 1000 500 r.HalfOpen (prelude.Integer t) true = r.Closed []
|
|
185
|
+
end
|
|
186
|
+
end
|
|
187
|
+
|
|
188
|
+
law `a bulkhead admits up to its limit` is
|
|
189
|
+
definition is
|
|
190
|
+
`for all` (running :: UInt8) .
|
|
191
|
+
r.bulkheadAdmit 4 (r.Bulkhead (prelude.Integer running)) 0 =
|
|
192
|
+
prelude.select (prelude.Integer running < 4)
|
|
193
|
+
(r.Step (r.Bulkhead (prelude.Integer running + 1)) r.Admit)
|
|
194
|
+
(r.Step (r.Bulkhead (prelude.Integer running)) (r.WaitFor 1000))
|
|
195
|
+
end
|
|
196
|
+
end
|
|
197
|
+
|
|
198
|
+
law `a sliding window admits n calls per period` is
|
|
199
|
+
definition is
|
|
200
|
+
`for all` (t :: UInt16) .
|
|
201
|
+
r.slidingWindowAdmit 2 1000 (r.SlidingWindow [prelude.Integer t, prelude.Integer t]) (prelude.Integer t + 1) =
|
|
202
|
+
r.Step (r.SlidingWindow [prelude.Integer t, prelude.Integer t]) (r.WaitFor 999)
|
|
203
|
+
end
|
|
204
|
+
end
|
|
205
|
+
|
|
206
|
+
-- Books a ticket under a fresh runtime: the stages whose undos ran.
|
|
207
|
+
compensationsFor :: Int64 -> List Text
|
|
208
|
+
|
|
209
|
+
law `a failed booking releases its seat` is
|
|
210
|
+
definition is
|
|
211
|
+
`for all` (n :: Int64) .
|
|
212
|
+
compensationsFor n = prelude.select (n < 0) ["reserveSeat"] []
|
|
213
|
+
end
|
|
214
|
+
end
|
|
215
|
+
|
|
216
|
+
-- Quotes a ticket under a runtime with the real clock: whether it timed out.
|
|
217
|
+
async quoteTimedOut :: Int64 -> Bool
|
|
218
|
+
|
|
219
|
+
law `a slow quote times out` is
|
|
220
|
+
definition is
|
|
221
|
+
`for all` (n :: Int64) . quoteTimedOut n = (n == -1)
|
|
222
|
+
end
|
|
223
|
+
example `a slow quote` is
|
|
224
|
+
n = -1
|
|
225
|
+
expect quoteTimedOut n = true
|
|
226
|
+
end
|
|
227
|
+
example `a quick quote` is
|
|
228
|
+
n = 0
|
|
229
|
+
expect quoteTimedOut n = false
|
|
230
|
+
end
|
|
231
|
+
end
|
|
232
|
+
|
|
233
|
+
-- Quotes a ticket under a runtime with the real clock: whether it succeeded
|
|
234
|
+
-- quickly (within 400ms), for ticket -2 through a hedged attempt.
|
|
235
|
+
async quoteHedged :: Int64 -> Bool
|
|
236
|
+
|
|
237
|
+
law `a stalled quote is hedged` is
|
|
238
|
+
definition is
|
|
239
|
+
`for all` (n :: Int64) . quoteHedged n = true
|
|
240
|
+
end
|
|
241
|
+
example `a stalled quote` is
|
|
242
|
+
n = -2
|
|
243
|
+
expect quoteHedged n = true
|
|
244
|
+
end
|
|
245
|
+
end
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
unit example.workflows
|
|
2
|
+
|
|
3
|
+
-- Workflows compose steps written by hand on each target. LawSpec generates
|
|
4
|
+
-- the composition itself, so a workflow behaves the same everywhere: every
|
|
5
|
+
-- stage below is a keyword, and each has a symbol too (>>=, <$>, <!>, <|>, ??).
|
|
6
|
+
|
|
7
|
+
type Signup is Signup name :: Text age :: Int32 end
|
|
8
|
+
type Account is Account name :: Text age :: Int32 level :: Int32 end
|
|
9
|
+
type SignupError is | MissingName | TooYoung | NameTooLong | Unavailable end
|
|
10
|
+
|
|
11
|
+
-- Checked definitions: LawSpec writes these on every target.
|
|
12
|
+
definition explain (reason :: Text) :: SignupError is TooYoung end
|
|
13
|
+
|
|
14
|
+
definition promote (a :: Account) :: Account is
|
|
15
|
+
match a with
|
|
16
|
+
| Account name age level -> Account name age 2
|
|
17
|
+
end
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
definition brief (a :: Account) :: Bool is
|
|
21
|
+
match a with
|
|
22
|
+
| Account name age level -> prelude.length name <= 8
|
|
23
|
+
end
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
definition tooLong (a :: Account) :: SignupError is NameTooLong end
|
|
27
|
+
|
|
28
|
+
definition nameOf (s :: Signup) :: Text is
|
|
29
|
+
match s with
|
|
30
|
+
| Signup name age -> name
|
|
31
|
+
end
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
-- Side steps and recovery handlers, also written by hand.
|
|
35
|
+
audit :: Account -> Bool
|
|
36
|
+
waitlist :: SignupError -> Either SignupError Account
|
|
37
|
+
|
|
38
|
+
-- The workflow's error type is declared, so every step must fail with
|
|
39
|
+
-- SignupError; checkAge fails with a reason, which mapError turns into one.
|
|
40
|
+
workflow register :: Signup -> Either SignupError Account is
|
|
41
|
+
checkName :: Signup -> Either SignupError Signup
|
|
42
|
+
retry exponential 100ms 2 3 max 1s jitter full
|
|
43
|
+
then checkAge :: Signup -> Either Text Signup
|
|
44
|
+
mapError explain
|
|
45
|
+
then openAccount :: Signup -> Either SignupError Account
|
|
46
|
+
map promote
|
|
47
|
+
tap audit
|
|
48
|
+
ensure brief else tooLong
|
|
49
|
+
orElse waitlist
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
-- With the error written as _, LawSpec generates GreetError, with one
|
|
53
|
+
-- constructor per step that can fail: GreetCheckNameFailed and GreetCheckAgeFailed.
|
|
54
|
+
workflow greet :: Signup -> Either _ Text is
|
|
55
|
+
checkName :: Signup -> Either SignupError Signup
|
|
56
|
+
>>= checkAge :: Signup -> Either Text Signup
|
|
57
|
+
<$> nameOf
|
|
58
|
+
?? anonymous
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
definition anonymous (e :: GreetError) :: Text is "guest" end
|
|
62
|
+
|
|
63
|
+
law `registering an account` is
|
|
64
|
+
definition is
|
|
65
|
+
`for all` (s :: Signup) .
|
|
66
|
+
prelude.isRight (register s) = (match s with
|
|
67
|
+
| Signup name age ->
|
|
68
|
+
prelude.length name > 0 && age >= 18 && prelude.length name <= 8
|
|
69
|
+
end)
|
|
70
|
+
end
|
|
71
|
+
example `a new account is promoted` is
|
|
72
|
+
s = Signup "ada" 30
|
|
73
|
+
expect register s = Right (Account "ada" 30 2)
|
|
74
|
+
end
|
|
75
|
+
example `a name is required` is
|
|
76
|
+
s = Signup "" 30
|
|
77
|
+
expect register s = Left MissingName
|
|
78
|
+
end
|
|
79
|
+
example `seventeen is too young` is
|
|
80
|
+
s = Signup "bob" 17
|
|
81
|
+
expect register s = Left TooYoung
|
|
82
|
+
end
|
|
83
|
+
example `a long name is rejected` is
|
|
84
|
+
s = Signup "bartholomew" 30
|
|
85
|
+
expect register s = Left NameTooLong
|
|
86
|
+
end
|
|
87
|
+
example `a taken name joins the waitlist` is
|
|
88
|
+
s = Signup "taken" 30
|
|
89
|
+
expect register s = Right (Account "waitlist" 18 0)
|
|
90
|
+
end
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
law `greeting never fails` is
|
|
94
|
+
definition is
|
|
95
|
+
`for all` (s :: Signup) . prelude.isRight (greet s) = true
|
|
96
|
+
end
|
|
97
|
+
example `a named greeting` is
|
|
98
|
+
s = Signup "ada" 30
|
|
99
|
+
expect greet s = Right "ada"
|
|
100
|
+
end
|
|
101
|
+
example `an anonymous greeting` is
|
|
102
|
+
s = Signup "" 30
|
|
103
|
+
expect greet s = Right "guest"
|
|
104
|
+
end
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
-- An all group runs its steps on the same state and combines their results.
|
|
108
|
+
-- With accumulate, every failing step's error is reported, in a generated
|
|
109
|
+
-- VetFailures constructor.
|
|
110
|
+
definition firstName (a :: Signup) (b :: Signup) :: Text is nameOf a end
|
|
111
|
+
|
|
112
|
+
workflow vet :: Signup -> Either _ Text is
|
|
113
|
+
all accumulate
|
|
114
|
+
then checkName
|
|
115
|
+
then checkAge
|
|
116
|
+
end
|
|
117
|
+
combine firstName
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
law `vetting reports every problem` is
|
|
121
|
+
definition is
|
|
122
|
+
`for all` (s :: Signup) .
|
|
123
|
+
prelude.isRight (vet s) = (match s with
|
|
124
|
+
| Signup name age -> prelude.length name > 0 && age >= 18
|
|
125
|
+
end)
|
|
126
|
+
end
|
|
127
|
+
example `no problems` is
|
|
128
|
+
s = Signup "ada" 30
|
|
129
|
+
expect vet s = Right "ada"
|
|
130
|
+
end
|
|
131
|
+
end
|
|
132
|
+
|
|
133
|
+
law `vetting a nameless child reports both problems` is
|
|
134
|
+
definition is
|
|
135
|
+
`for all` (age :: Int8 where age >= 0 && age < 18) .
|
|
136
|
+
vet (Signup "" (prelude.Int32 age)) = Left (VetFailures [VetCheckNameFailed MissingName, VetCheckAgeFailed "too young"])
|
|
137
|
+
end
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
law `vetting a named child reports its age` is
|
|
141
|
+
definition is
|
|
142
|
+
`for all` (age :: Int8 where age >= 0 && age < 18) .
|
|
143
|
+
vet (Signup "ada" (prelude.Int32 age)) = Left (VetFailures [VetCheckAgeFailed "too young"])
|
|
144
|
+
end
|
|
145
|
+
end
|
package/index.d.ts
CHANGED
package/package.json
CHANGED
package/templates.mjs
CHANGED
|
@@ -93,11 +93,11 @@ const scaffolds = {
|
|
|
93
93
|
"kotlin": {
|
|
94
94
|
"readable": {
|
|
95
95
|
"settings.gradle.kts": "rootProject.name = \"lawspec-example\"\n",
|
|
96
|
-
"build.gradle.kts": "plugins {\n kotlin(\"jvm\") version \"2.3.21\"\n}\n\nrepositories {\n mavenCentral()\n}\n\nkotlin {\n jvmToolchain(25)\n}\n\ndependencies {\n testImplementation(\"io.kotest:kotest-runner-junit5:5.9.1\")\n testImplementation(\"io.kotest:kotest-assertions-core:5.9.1\")\n testImplementation(\"io.kotest:kotest-property:5.9.1\")\n}\n\ntasks.test {\n useJUnitPlatform()\n}\n"
|
|
96
|
+
"build.gradle.kts": "plugins {\n kotlin(\"jvm\") version \"2.3.21\"\n}\n\nrepositories {\n mavenCentral()\n}\n\nkotlin {\n jvmToolchain(25)\n}\n\ndependencies {\n implementation(\"org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0\")\n testImplementation(\"io.kotest:kotest-runner-junit5:5.9.1\")\n testImplementation(\"io.kotest:kotest-assertions-core:5.9.1\")\n testImplementation(\"io.kotest:kotest-property:5.9.1\")\n}\n\ntasks.test {\n useJUnitPlatform()\n}\n"
|
|
97
97
|
},
|
|
98
98
|
"compact": {
|
|
99
99
|
"settings.gradle.kts": "rootProject.name = \"lawspec-example\"\n",
|
|
100
|
-
"build.gradle.kts": "plugins { kotlin(\"jvm\") version \"2.3.21\" }\nrepositories { mavenCentral() }\nkotlin { jvmToolchain(25) }\ndependencies { testImplementation(\"io.kotest:kotest-runner-junit5:5.9.1\"); testImplementation(\"io.kotest:kotest-assertions-core:5.9.1\"); testImplementation(\"io.kotest:kotest-property:5.9.1\") }\ntasks.test { useJUnitPlatform() }\n"
|
|
100
|
+
"build.gradle.kts": "plugins { kotlin(\"jvm\") version \"2.3.21\" }\nrepositories { mavenCentral() }\nkotlin { jvmToolchain(25) }\ndependencies { implementation(\"org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0\"); testImplementation(\"io.kotest:kotest-runner-junit5:5.9.1\"); testImplementation(\"io.kotest:kotest-assertions-core:5.9.1\"); testImplementation(\"io.kotest:kotest-property:5.9.1\") }\ntasks.test { useJUnitPlatform() }\n"
|
|
101
101
|
}
|
|
102
102
|
},
|
|
103
103
|
"rust": {
|
package/test-command.mjs
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
// Generated from templates/npm/test-command.mjs by lawspec-dev generate. Do not edit.
|
|
2
|
+
// lawspec test: run the generated tests of the laws whose results may have
|
|
3
|
+
// changed since their last passing run, through each target's own runner.
|
|
4
|
+
//
|
|
5
|
+
// A law's result is keyed by everything it depends on: its plan key (the law
|
|
6
|
+
// and the Merkle digests of the types and definitions it reaches), the
|
|
7
|
+
// compiler build, the target's configuration, its unit's generated test file,
|
|
8
|
+
// the project's build and lock files, the toolchain the doctor reports and, for
|
|
9
|
+
// a law that calls adapters, every file in the target project that LawSpec
|
|
10
|
+
// did not generate. A passing run records each law's key and seed; a law runs
|
|
11
|
+
// again when its key changes or with --fresh.
|
|
12
|
+
import { createHash } from "node:crypto";
|
|
13
|
+
import { readdir, readFile, stat } from "node:fs/promises";
|
|
14
|
+
import path from "node:path";
|
|
15
|
+
|
|
16
|
+
// Folders that hold dependencies, build output or caches, not code under test.
|
|
17
|
+
const skipped = new Set([".git", ".lawspec", "node_modules", "dist", "build", "target", "out", ".gradle",
|
|
18
|
+
".stack-work", "__pycache__", ".hypothesis", ".pytest_cache", ".venv", "venv", ".idea", ".vscode"]);
|
|
19
|
+
// Build and lock files, which choose the toolchain and dependencies.
|
|
20
|
+
const environmentFiles = ["package.json", "package-lock.json", "tsconfig.json", "pyproject.toml", "go.mod",
|
|
21
|
+
"go.sum", "pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts",
|
|
22
|
+
"Cargo.toml", "Cargo.lock", "stack.yaml", "stack.yaml.lock", "package.yaml"];
|
|
23
|
+
|
|
24
|
+
const digest = (value) => createHash("sha256").update(value).digest("hex");
|
|
25
|
+
|
|
26
|
+
// Every file in a project that LawSpec did not generate, by content.
|
|
27
|
+
export async function projectDigest(root, generated) {
|
|
28
|
+
const hash = createHash("sha256");
|
|
29
|
+
async function walk(folder) {
|
|
30
|
+
const entries = (await readdir(path.join(root, folder), { withFileTypes: true }))
|
|
31
|
+
.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
32
|
+
for (const entry of entries) {
|
|
33
|
+
const relative = folder ? `${folder}/${entry.name}` : entry.name;
|
|
34
|
+
if (entry.isDirectory()) {
|
|
35
|
+
if (!skipped.has(entry.name) && !relative.endsWith("testdata/rapid")) await walk(relative);
|
|
36
|
+
} else if (entry.isFile() && !generated.has(relative)) {
|
|
37
|
+
hash.update(relative + "\0").update(await readFile(path.join(root, relative))).update("\0");
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
await walk("");
|
|
42
|
+
return hash.digest("hex");
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export async function environmentDigest(root, report) {
|
|
46
|
+
const parts = [JSON.stringify(report ?? null)];
|
|
47
|
+
const names = (await readdir(root)).filter((name) => environmentFiles.includes(name) || name.endsWith(".cabal")).sort();
|
|
48
|
+
for (const name of names) parts.push(name, await readFile(path.join(root, name), "utf8"));
|
|
49
|
+
return digest(JSON.stringify(parts));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
// The result key of each law in a target's test manifest.
|
|
53
|
+
export function lawKeys({ build, target, machineBits, minify, tests, files, environment, project }) {
|
|
54
|
+
const contents = new Map(files.map((file) => [file.path, file.content]));
|
|
55
|
+
const configuration = JSON.stringify({ ...target, root: undefined });
|
|
56
|
+
return new Map(tests.map((entry) => [entry.law, digest(JSON.stringify([
|
|
57
|
+
build, configuration, machineBits, minify, entry.key, digest(contents.get(entry.file) ?? ""),
|
|
58
|
+
environment, entry.callsAdapters ? project : null,
|
|
59
|
+
]))]));
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const regex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
63
|
+
const without = (file, extension) => file.slice(0, -extension.length);
|
|
64
|
+
const groupBy = (entries, key) => {
|
|
65
|
+
const groups = new Map();
|
|
66
|
+
for (const entry of entries) groups.set(key(entry), [...(groups.get(key(entry)) ?? []), entry]);
|
|
67
|
+
return [...groups.entries()];
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
// The native invocations that run exactly the given laws' tests, each with
|
|
71
|
+
// the laws it covers and how to tell, from the runner's own report, which of
|
|
72
|
+
// them ran. Names are matched whole, so law1 never selects law10. `scratch`
|
|
73
|
+
// is a folder for reports.
|
|
74
|
+
export function invocations(target, entries, { offline = false, scratch = "." } = {}) {
|
|
75
|
+
const language = target.language;
|
|
76
|
+
const testDir = target.testDir;
|
|
77
|
+
const relativeTo = (file, defaultDir) => {
|
|
78
|
+
const directory = testDir || defaultDir;
|
|
79
|
+
return file.startsWith(directory + "/") ? file.slice(directory.length + 1) : file;
|
|
80
|
+
};
|
|
81
|
+
const tests = (entry) => [`law${entry.index}Example*`, `law${entry.index}Boundary*`, `law${entry.index}Property*`];
|
|
82
|
+
const kinds = (entry) => new RegExp(`^law${entry.index}(Example|Boundary|Property)`);
|
|
83
|
+
const className = (file, defaultDir, extension) => without(relativeTo(file, defaultDir), extension).replaceAll("/", ".");
|
|
84
|
+
if (language === "python")
|
|
85
|
+
return groupBy(entries, (e) => e.file).map(([file, laws], n) => {
|
|
86
|
+
const report = path.join(scratch, `pytest-${n}.xml`);
|
|
87
|
+
return { laws, command: target.python || "python3",
|
|
88
|
+
args: ["-m", "pytest", "-q", file, "-k", laws.map((e) => `test_law${e.index}_`).join(" or "), `--junitxml=${report}`],
|
|
89
|
+
report: { kind: "junit", files: [report] },
|
|
90
|
+
ran: (test) => laws.filter((e) => test.name.startsWith(`test_law${e.index}_`)) };
|
|
91
|
+
});
|
|
92
|
+
if (language === "javascript" || language === "typescript") {
|
|
93
|
+
const pattern = (e) => `^${regex(e.label)}( example: .*| property)?$`;
|
|
94
|
+
const files = [...new Set(entries.map((e) => language === "typescript"
|
|
95
|
+
? `dist/${without(e.file, ".ts")}.js` : e.file))];
|
|
96
|
+
const report = path.join(scratch, "node.xml");
|
|
97
|
+
const run = { laws: entries, command: process.execPath,
|
|
98
|
+
args: ["--test", `--test-name-pattern=(${entries.map(pattern).join("|")})`,
|
|
99
|
+
"--test-reporter=spec", "--test-reporter-destination=stdout",
|
|
100
|
+
"--test-reporter=junit", `--test-reporter-destination=${report}`, ...files],
|
|
101
|
+
report: { kind: "junit", files: [report] },
|
|
102
|
+
ran: (test) => entries.filter((e) => new RegExp(pattern(e)).test(test.name)) };
|
|
103
|
+
return language === "typescript"
|
|
104
|
+
? [{ laws: [], command: "npm", args: ["exec", "--", "tsc", "-p", "tsconfig.json"] }, run]
|
|
105
|
+
: [run];
|
|
106
|
+
}
|
|
107
|
+
if (language === "go")
|
|
108
|
+
return groupBy(entries, (e) => path.posix.dirname(e.file)).map(([directory, laws]) => ({
|
|
109
|
+
laws, command: "go",
|
|
110
|
+
args: ["test", "-json", "-count=1", `./${directory}`, "-run", `^TestLaw(${laws.map((e) => e.index).join("|")})(Example|Boundary|Property)`],
|
|
111
|
+
report: { kind: "go-json" },
|
|
112
|
+
ran: (test) => laws.filter((e) => new RegExp(`^TestLaw${e.index}(Example|Boundary|Property)`).test(test.name)) }));
|
|
113
|
+
if (language === "java") {
|
|
114
|
+
const byClass = groupBy(entries, (e) => className(e.file, "src/test/java", ".java"));
|
|
115
|
+
return [{ laws: entries, command: target.maven || "mvn",
|
|
116
|
+
args: [...(offline ? ["-o"] : []), "-B", "test", `-Dtest=${byClass.map(([name, laws]) => `${name}#${laws.flatMap(tests).join("+")}`).join(",")}`],
|
|
117
|
+
report: { kind: "junit", directory: "target/surefire-reports" },
|
|
118
|
+
ran: (test) => entries.filter((e) => test.classname === className(e.file, "src/test/java", ".java") && kinds(e).test(test.name)) }];
|
|
119
|
+
}
|
|
120
|
+
// Kotest names tests by string, which Gradle's method filters cannot
|
|
121
|
+
// select. Kotest's own filter selects them within each class: one pattern,
|
|
122
|
+
// matched against whole names, whose * becomes .*? (several comma-separated
|
|
123
|
+
// patterns must all match, so alternatives go in one group).
|
|
124
|
+
if (language === "kotlin")
|
|
125
|
+
return groupBy(entries, (e) => e.file).map(([file, laws]) => {
|
|
126
|
+
const filter = `(${laws.flatMap((e) => ["Example", "Boundary", "Property"].map((kind) => `law${e.index}${kind}`)).join("|")})*`;
|
|
127
|
+
const name = className(file, "src/test/kotlin", ".kt");
|
|
128
|
+
return { laws, command: target.gradle || "gradle",
|
|
129
|
+
args: [...(offline ? ["--offline"] : []), "--console=plain", "test", "--rerun", "--tests", name],
|
|
130
|
+
env: { "kotest.filter.tests": filter, kotest_filter_tests: filter },
|
|
131
|
+
report: { kind: "junit", directory: "build/test-results/test" },
|
|
132
|
+
ran: (test) => laws.filter((e) => test.classname === name && kinds(e).test(test.name)) };
|
|
133
|
+
});
|
|
134
|
+
if (language === "rust")
|
|
135
|
+
return groupBy(entries, (e) => e.file).map(([file, laws]) => ({
|
|
136
|
+
laws, command: "cargo",
|
|
137
|
+
args: ["test", ...(offline ? ["--offline"] : []), "--test", path.posix.basename(file, ".rs"), "--", "--exact",
|
|
138
|
+
...laws.map((e) => `test_${e.index}`)],
|
|
139
|
+
report: { kind: "lines", pattern: /^test (test_\d+) \.\.\. (ok|FAILED)/ },
|
|
140
|
+
ran: (test) => laws.filter((e) => test.name === `test_${e.index}`) }));
|
|
141
|
+
if (language === "haskell") {
|
|
142
|
+
const module = (e) => without(relativeTo(e.file, "test"), "Spec.hs").replaceAll("/", ".");
|
|
143
|
+
const matches = entries.flatMap((e) => ["Example", "Boundary", "Property"].map((kind) => `${module(e)}/law${e.index}${kind}`));
|
|
144
|
+
return [{ laws: entries, command: "stack",
|
|
145
|
+
args: ["--no-terminal", "test", "--test-arguments", matches.map((m) => `--match ${m}`).join(" ")],
|
|
146
|
+
report: { kind: "hspec" },
|
|
147
|
+
ran: (test) => entries.filter((e) => test.classname === module(e) && kinds(e).test(test.name)) }];
|
|
148
|
+
}
|
|
149
|
+
throw new Error(`lawspec test does not support ${language}`);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
// The tests a run executed, as {name, classname}, from the runner's report or
|
|
153
|
+
// output. Skipped tests are not counted.
|
|
154
|
+
export async function executedTests(report, output, root, since) {
|
|
155
|
+
if (report?.kind === "junit") {
|
|
156
|
+
const files = report.files ?? await reportFiles(path.join(root, report.directory), since);
|
|
157
|
+
const tests = [];
|
|
158
|
+
for (const file of files) {
|
|
159
|
+
const xml = await readFile(path.resolve(root, file), "utf8").catch(() => "");
|
|
160
|
+
for (const match of xml.matchAll(/<testcase\b([^>]*?)(\/>|>([\s\S]*?)<\/testcase>)/g)) {
|
|
161
|
+
if (/<skipped\b/.test(match[3] ?? "")) continue;
|
|
162
|
+
const attribute = (name) => unescapeXml(match[1].match(new RegExp(`\\b${name}="([^"]*)"`))?.[1] ?? "");
|
|
163
|
+
tests.push({ name: attribute("name").replace(/\(\)$/, ""), classname: attribute("classname") });
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
return tests;
|
|
167
|
+
}
|
|
168
|
+
if (report?.kind === "go-json")
|
|
169
|
+
return output.split("\n").flatMap((line) => {
|
|
170
|
+
try {
|
|
171
|
+
const event = JSON.parse(line);
|
|
172
|
+
return ["pass", "fail"].includes(event.Action) && event.Test ? [{ name: event.Test, classname: event.Package }] : [];
|
|
173
|
+
} catch { return []; }
|
|
174
|
+
});
|
|
175
|
+
if (report?.kind === "lines")
|
|
176
|
+
return output.split("\n").flatMap((line) => {
|
|
177
|
+
const match = line.match(report.pattern);
|
|
178
|
+
return match ? [{ name: match[1], classname: "" }] : [];
|
|
179
|
+
});
|
|
180
|
+
if (report?.kind === "hspec") {
|
|
181
|
+
// hspec prints each module, then its examples indented beneath it.
|
|
182
|
+
const tests = [];
|
|
183
|
+
let module = "";
|
|
184
|
+
for (const line of output.split("\n")) {
|
|
185
|
+
if (/^\S/.test(line) && !/^(Finished|Failures|Randomized|\d+ examples?)/.test(line)) module = line.trim();
|
|
186
|
+
const example = line.match(/^\s+(law\d+\S*?):?(?:\s.*)?\s\[[✔✘]\]\s*$/);
|
|
187
|
+
if (example) tests.push({ name: example[1], classname: module });
|
|
188
|
+
}
|
|
189
|
+
return tests;
|
|
190
|
+
}
|
|
191
|
+
return [];
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
async function reportFiles(directory, since) {
|
|
195
|
+
const names = await readdir(directory).catch(() => []);
|
|
196
|
+
const files = [];
|
|
197
|
+
for (const name of names.filter((n) => n.endsWith(".xml"))) {
|
|
198
|
+
const info = await stat(path.join(directory, name));
|
|
199
|
+
if (info.mtimeMs >= since) files.push(path.join(directory, name));
|
|
200
|
+
}
|
|
201
|
+
return files;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
const unescapeXml = (text) => text.replaceAll("<", "<").replaceAll(">", ">").replaceAll(""", '"')
|
|
205
|
+
.replaceAll("'", "'").replaceAll("'", "'").replaceAll("&", "&");
|