-
Notifications
You must be signed in to change notification settings - Fork 16
/
chai.javascript.txt
357 lines (284 loc) · 20.2 KB
/
chai.javascript.txt
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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
CHAI
ALTERNATIVES ==> #Prefer using assertions built-in the test runner if available
#Otherwise:
# - Node.js core ASSERT module (prefer if wants minimalistic)
# - Deno (prefer with Deno)
# - chai (prefer if wants expressive)
# - should.js:
# - lots of features
# - very similar to chai:
# - a bit less known
# - a little easier to add extensions
# - use less flags (i.e. get property descriptors) and does not change the
# current value in the chain, which can be confusing
# - power-assert:
# - uses Node.js ASSERT standard API
# - parses JavaScript AST (with Esprima) to give detailed error message including
# assert() argument values
# - requires additional instrumentation because of this parsing
# - not too maintained
# - must.js: not maintained
# - unexpected: lots of features but less known
# - jasmine assertions:
# - integrated with jasmine
# - more verbose and a little less features
# - jasmine-matchers: Jasmine-specific
# - jasmine-utils: Jasmine-specific
# - expect-more:
# - Jasmine|Jest-specific
# - curried
# - not maintained
# - jest assertions:
# - integrated with jest
# - more verbose and a little less features
# - snapshots testing
# - jest-extended:
# - Jest-specific
# - many more assertions, similar to chai or should.js
# - not well maintained
# - ava assertions:
# - Ava-specific
# - minimalistic, close to Node.js core ASSERT module
# - do not throw on failure
# - tape assertions:
# - Tape-specific
# - minimalistic, close to Node.js core ASSERT module
# - do not throw on failure
# - tape assertions:
# - Node-tap-specific
# - minimalistic, close to Node.js core ASSERT module
# - do not throw on failure
# - tape-modern assertions:
# - Node-tap-specific
# - very minimalistic, close to Node.js core ASSERT module
# - do not throw on failure
VERSION ==> #5.1.1
#Node.js or browser
MOCHA ==> #Usually used by Mocha, but does not have to
/=+===============================+=\
/ : : \
)==: BASE :==(
\ :_______________________________: /
\=+===============================+=/
VAL.should #SHOULD
#CHAI.should() must first be fired to extend OBJ prototype with OBJ.should
#VAL cannot be null|undefined
CHAI.expect(VAL) #SHOULD
new CHAI.Assertion(VAL) #SHOULD
CHAI.assert(VAL) #SHOULD
#Uses another naming conventions for the assertions (not documented here)
SHOULD #Object wrapping VAL, which is accessed with SHOULD._obj
SHOULD CHAIN ==> #All members returns SHOULD, so can be chained, e.g. VAL.should.exist.and.be.ok
#There are two types of members along the chains:
# - methods: assertion on SHOULD._obj, internally using SHOULD.assert()
# - properties: add an internal "flag" along the chain, that will influence next methods
CONFIG VAR ==> #Can be used by Mocha reporters
CHAI.config.includeStack #Show stack trace (def: false)
CHAI.config.showDiff #Show diff (def: true)
CHAI.config.truncateThreshold #Truncates VAL length (def: 40, 0 to disable)
/=+===============================+=\
/ : : \
)==: GENERIC :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD.be #
SHOULD.have[.been] #
SHOULD...that|which
[.is|has[.been]|does] #
SHOULD...and|but #
SHOULD.with|at|of|same|to|still #Same as SHOULD (doesn't do anything), provided only for BDD-style syntax
SHOULD.not #Negation
SHOULD.satisfy[ies]
(FUNC(VAL)->BOOL) #
SHOULD.equal(VAL) #===. Compare OBJ by reference.
SHOULD.deep.equal(VAL) #===. Compare OBJ by copy (including inherited) (using Object.is())
SHOULD.eql(VAL) #Like deep.equal() except "deep" flag is not set
SHOULD.be.oneOf(ARR) #=== one of ARR values
SHOULD.[be.a[n]](STR) #Uses type-detect (see its doc)
SHOULD.[be.an.]instanceof(FUNC) #VAL instanceof TYPE
SHOULD.[be.]arguments #Is arguments object
/=+===============================+=\
/ : : \
)==: NULL|UNDEFINED :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD.[be.]null|undefined #=== null|undefined
SHOULD.exist #!== null|undefined
CHAI.should().[not.]exist(VAL) #When using VAL.should
/=+===============================+=\
/ : : \
)==: BOOLEAN :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD.[be.]true|false #=== true|false
SHOULD.[be.]ok #== true|false
/=+===============================+=\
/ : : \
)==: NUMBER :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD.[be.]NaN #Object.is(NaN)
SHOULD.[be.]finite #Number.isFinite()
SHOULD.[be.]above|[at.]least|
below|[at.]most(NUM) #> >= < <=
SHOULD.[be.]within(NUM, NUM2) #> and <
SHOULD.[be.]closeTo|approximately
(NUM, NUM2) #>= NUM-NUM2 and <= NUM+NUM2
/=+===============================+=\
/ : : \
)==: STRING :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD_STR.match[es](REGEXP) #REGEXP.test()
SHOULD_STR.
include[s]|contain[s](STR2)
SHOULD_STR.[have.]string(STR2) #STR2 is inside STR
SHOULD_STR.[have.]lengthOf
[.above|below|least|most|within]
(NUM) #STR.length === > < >= <= NUM
SHOULD_STR.[be.]empty #STR.length === 0
/=+===============================+=\
/ : : \
)==: ARRAY|OBJECT :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD_ARR|SET|MAP.
[deep.]include[s]|contain[s](VAL)#One value [deep.]equal(VAL)
SHOULD_ARR|SET|MAP.
[deep.]include[s]|contain[s]
.oneOf(ARR) #One value [deep.]equal(one of ARR)
SHOULD_ARR.
[have|include[s]|contain[s].] #ARR2 have exact same values (or is subset if "include") as ARR (using [deep.]equal())
[deep.][ordered.]members(ARR2) #Unless "ordered", can be in different order
SHOULD_OBJ.[deep.][own|nested.] #OBJ2 [deep] subset of OBJ
include[s]|contain[s](OBJ2) #If "own", non-inherited only.
#If "nested", OBJ2 keys can be a dot|bracket-delimited VARR
SHOULD_OBJ|ARR.[have.][deep.] #Check property exists.
[own|nested.]property #"own|nested": like include()
('PROP'[,VAL])[.that[.is]|with...]#If VAL, also checks property [deep.]equal(VAL)
#The assertion value from OBJ to OBJ.PROP for the rest of the chain, e.g.:
# SHOULD_OBJ.have.property(...).that.is.true.with.property(...).that.is.false
SHOULD_OBJ|ARR.[have.]
ownPropertyDescriptor
('PROP'[, VAL])][...] #Same except VAL (and the new assertion value) is the object descriptor
SHLD_OBJ|ARR|MAP|SET.
have|contain.any.[deep.]key[s]
('PROP'[_ARR]...) #At least one property should exist
SHOULD_OBJ|ARR|MAP|SET.
include|contain.all.[deep.]key[s]
('PROP'[_ARR]...) #All properties should exist
SHOULD_OBJ|ARR|MAP|SET.
have.[all.][deep.]key[s]
('PROP'[_ARR]...) #All properties should exist, and no other properties should exist
SHOULD_OBJ.[itself.]respondTo #Check property exists and it is a function.
('FUNC') #Not through prototype if "itself"
SHOULD_OBJ|ARR|MAP|SET
.[have.]lengthOf
[.above|below|least|most|within]
(NUM) #OBJ|ARR|MAP|SET.length === > < >= <= NUM
SHOULD_OBJ|ARR|MAP|SET.[be.]empty #OBJ|ARR|MAP|SET.length === 0
SHOULD_OBJ.be.
extensible|sealed|frozen #Check Object.isExtensible|Sealed|Frozen()
SHOULD_ITERABLE.be.iterable #Is sync ITERABLE
/=+===============================+=\
/ : : \
)==: FUNCTION :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD_FUNC.throw[s] #Should throw.
([ERROR|ErrorType], [REGEXP|STR])#The assertion value becomes ERROR for rest of the chain.
SHOULD_FUNC.change[s](FUNC2)
SHOULD_FUNC.change[s](OBJ, 'PROP')#FUNC() return value or OBJ.PROP should be different before|after FUNC() called
SHOULD_FUNC.
increase[s]|decrease[s](...)
[by.(NUM)] #Same but for increment|decrement
/=+===============================+=\
/ : : \
)==: DATE :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD_DATE.equal|before| ##With "Date": same but truncates after day.
afterTime|Date(DATE2) ##Module chai-datetime 1.4.0
SHOULD_DATE.withinTime|Date
(DATE2, DATE3) ##
/=+===============================+=\
/ : : \
)==: PROMISE :==(
\ :_______________________________: /
\=+===============================+=/
CHAI-AS-PROMISED ==> ##Module chai-as-promised (8.0.0)
CHAIPROMISE ##PROMISE with only then(FUNC, FUNC2) member returned by every methods below.
##To extend it:
## - use CHAIASPROMISED.setTransferPromiseness(FUNC(SHOULD, PROMISE))
## - where FUNC() assigns SHOULD.then|catch|finally = PROMISE.FUNC.bind(PROMISE)
CHAIPROMISE.notify(FUNC) ##Calls FUNC([ERROR]) when CHAIPROMISE is resolved|rejected
CHAIASPROMSD
.setTransformAsserterArgs ##Maps arguments passed to assertion functions when "eventually" or "rejectedWith" is used
(FUNC(ARR)->[PROMISE_]ARR) ##Example use: allow doing SHOULD_PROMISE.become(PROMISE_VAL)
async|await ##Every CHAIPROMISE returned needs to be handled either by:
## - returning it in it()
## - using await
##Also simply using async|await is better than using fulfilled|eventually|become(),
##but rejected[With] are still useful.
SHOULD_PROMISE.[be.]fulfilled ##PROMISE should be resolved.
SHOULD_PROMISE. ##PROMISE should be resolved and resolve with VAL and VAL.should.FUNC2(...).
eventually.FUNC2(...) ##Prefer async|await
SHOULD_PROMISE.become(VAL) ##Same as SHOULD_PROMISE.eventually.deep.equal(VAL)
SHOULD_PROMISE.[be.]rejected
SHOULD_PROMISE.
[be.]rejectedWith(VAL) ##PROMISE should be rejected [with VAL]
/=+===============================+=\
/ : : \
)==: EXTENSIONS :==(
\ :_______________________________: /
\=+===============================+=/
SHOULD.assert(BOOL, STR[()], #Throws AssertionError('MESSAGE') if BOOL false. Noop if BOOL true.
STR2[()][, VAL][, VAL2]) #Used internally by all assertion methods.
#STR[2]:
# - positive|negative error message
# - usually "expected ... to VERB ..."
# - can include following template patterns:
# - "#{this}": SHOULD._obj
# - "#{exp}": VAL (expected value)
# - "#{act}": VAL2 (def: SHOULD._obj) (actual value)
#"Internal error message":
# - STR3 prepended to error message (def: "")
# - specified as optional last argument to all assertion method, or to new CHAI.Assertion(VAL, STR)
# - usually specific to the calling code, not to the generic assertion problem
CHAIUTILS.flag #Gets|sets a "flag"
(SHOULD, 'VAR'[, 'VAL']) #Some flags used by most assertions:
# - "object": underlying VAL. Can also use SHOULD._obj
# - "message": "internal error message"
# - "negate" BOOL: flag .not
# - "deep" BOOL: flag .deep
# - "contains" BOOL: flag .include.*
# - "length" BOOL: flag .length.*
#When creating a new flag, should either create properties|methods handling it,
#or overwrite current ones.
CHAIUTILS.transferFlags #Copy this's flags to SHOULD, except "object" and "message" (unless BOOL is true)
(this, SHOULD[, BOOL]) #To use on final assertions inside a custom property|method, that create a SHOULD,
#to make sure flags are propagated.
#Not to use:
# - when checking preconditions
# - on final assertions with SHOULD.assert() (not affected by flags)
CHAI.use(FUNC(CHAI, CHAIUTILS)) #Fires FUNC().
#FUNC are usually plugins MODULE which fire CHAI.Assertion.*
CHAI.Assertion.addProperty #Makes SHOULD.PROP firing FUNC2() with SHOULD as this.
('PROP', FUNC2()) #Usually meant to:
# - assert preconditions with this.*
# - use CHAIUTILS.flag()
CHAI.Assertion.addMethod #Same for SHOULD.FUNC(...).
('FUNC', FUNC2(...)) #Usually FUNC2() includes actual assertions (as opposed to preconditions) with this.assert()
CHAI.Assertion.addChainableMethod #Same as CHAI.Assertion.addMethod(STR, FUNC); CHAI.Assertion.addProperty(STR, FUNC2), except:
(STR, FUNC, FUNC2) # - it cannot be overwritten (case of a, an, include, length)
# - method FUNC() also fire property FUNC2()
CHAI.Assertion.overwriteMethod #Overwrite SHOULD.FUNC(...)
('FUNC', FUNC3(SUPER)->FUNC2(...))#If SHOULD.FUNC() is overwritten only for specific preconditions (e.g. if input is HTML),
#can call original method with SUPER.call(this, ...)
CHAI.Assertion.overwriteProperty
('PROP', FUNC3(SUPER)->FUNC2()) #Same for SHOULD.PROP
CHAI.Assertion.
overwriteChainableMethod
(STR, FUNC3, FUNC4) #