-
Notifications
You must be signed in to change notification settings - Fork 16
/
mocha.node_cli.txt
351 lines (273 loc) · 20.7 KB
/
mocha.node_cli.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
MOCHA
ALTERNATIVES ==> # - Mocha:
# - minimalistic
# - no CPU parallelism, unbounded I/O parallelism through library
# - Ava (preferred server-side):
# - less modular: runner + simple assertions + diff testing
# - unbounded I/O parallelism (concurrent tests), bounded CPU parallelism (CHILD_PROCESS.fork() each test file)
# - includes power-assert
# - includes babel
# - only server-side
# - Jest (preferred client-side):
# - much less modular: runner + assertions + data-driven testing + mocks/spies + timers mocks + modules mocks
# + diff testing + memory leaks detection + test coverage
# - test-framework-like features:
# - can be used to run other logic than testing (e.g. linting or compiling)
# - can pre-process files (e.g. Babel)
# - unbounded I/O parallelism (concurrent tests), bounded CPU parallelism (CHILD_PROCESS.fork() each test file)
# - interactive mode
# - nice reporting
# - can test only modified files
# - global sandboxing, including JSDOM
# - Jasmine:
# - less modular (runner + assertions + mocks/spies + timers mocks + XHR mocks)
# - less reporters
# - less features as a runner
# - no parallelism
# - QUnit: more TDD than BDD. Not as many features
# - Tape:
# - TAP serializer
# - in-JavaScript (no external test runner)
# - minimalistic: no PROMISE support, hooks, selection, bail, watch
# - no parallelism
# - no exception handling, and failed assertions do not throw
# - tape-modern: similar to tape but:
# - no need for TEST.end()
# - exception handling
# - slightly less TAP output capability
# - less test runners features: timeout, process 'exit' handler
# - node-tap:
# - less modular: runner + simple assertions + diff testing + test coverage
# - TAP output, but not great, so should use built-in reporters (similar to Mocha's)
# - either in-JavaScript or external test runner
# - bounded I/O parallelism (concurrent tests), bounded CPU parallelism (CHILD_PROCESS.spawn() each test file)
# - bad exception handling, failed assertions do not throw
# - can run only previously failed tests
# - "test" core module:
# - part of Node.js core
# - TAP output
# - fewer features
# - Deno test (preferred with Deno)
# - Deno std library
# - much less modular: runner + assertions + mocks/spies + timers mocks + diff testing + IO leaks detection
# + test coverage + TypeScript test coverage
# - no great I/O parallelism (between files, but not inside), no bounded CPU parallelism (single process)
# - simple configuration-less reporting
# - no timeout
VERSION ==> #10.2.0
#Node.js, browser and CLI
REPORTERS ==> #See Mocha reporters doc
/=+===============================+=\
/ : : \
)==: TESTS :==(
\ :_______________________________: /
\=+===============================+=/
describe(STR, FUNC()) #FUNC must fire it|before|after[Each]()
#But can do any JavaScript, e.g. data-driven testing:
# ARR.forEach(VAL => it(STR + VAL, FUNC2))
#Nested describe() will create indentations.
#Using an already defined describe(STR) will get it instead of setting it.
it(STR, FUNC([FUNC2])) #Will be async if:
# - FUNC2 is defined (or mocha -A|--async-only is used),
# in which case must fire FUNC2([ERROR])
# - return PROMISE
#To make test fail, throw an ERROR
before|after([STR, ]FUNC([FUNC2]))#Fire FUNC() once before|after the current describe() or (if none) all describe()
#Child describe()'s before() are fired after their parent, after() before their parent.
#STR is description. Only shown when FUNC() fails.
before|afterEach
([STR, ]FUNC([FUNC2])) #Same but fired once for each it() instead
-r MODULE #Fires require(MODULE) at beginning
--require MODULE #Can return an OBJ with:
# - mochaHooks.before|afterAll|Each FUNC[_ARR]: run in each test file
# - mochaGlobalSetup|Teardown FUNC: run once before|after all test files
this #Is shared by all it|before|after[Each]() in a given describe()
#Child describe() get a shallow copy.
#Because of this, arrow functions should not be used
this.* #Contains some information about current it|before|after[Each](),
#e.g. title, body, timeout, async, skip, parent|children
run() #Starts all run tests.
#Only available when mocha --delay was used.
#Useful when setting up describe() is async
-u STR #How functions are named:
--ui STR # - "bdd" (def): describe|context(), it|specify(), before|after[Each]()
# - "require": same as "bdd" but must const { describe, ... } = require('mocha')
# - "tdd": suite(), test(), [suite]setup|teardown()
# - "exports": module.exports = { before|after[Each](...), STR: { ...: FUNC(...) } }
# - "qunit": suite(), test(), before|afterEach(), but without nesting
#Custom ones can be created (see online doc)
/=+===============================+=\
/ : : \
)==: CONFIG :==(
\ :_______________________________: /
\=+===============================+=/
CONF #Can be:
# - --[no-]OPT
# - --config=FILE or --no-config
# - ./.mocharc.js|json|y[a]ml|jsonc
# - PACKAGE.mocha OBJ
# - --package=PACKAGE.json or --no-package
/=+===============================+=\
/ : : \
)==: SELECTION :==(
\ :_______________________________: /
\=+===============================+=/
describe.skip(...) #Skip this
it.skip(...) #Can also omit FUNC
this.skip() #Same inside it|before[Each]()
describe.only(...)
it.only(...) #Only run this
--forbid-only|pending #Disallow it.only|skip()
mocha [FILE|DIR...] #Runs test files
#Def: ./test/*.js|mjs
--recursive #Looks recursively into DIR
#Def will be ./test
--ignore 'FILE|GLOB' #Exclude files (uses Minimatch, see its doc)
--extension 'EXT' #
-g REGEXP #Only run test cases which description matching partially REGEXP
--grep REGEXP #Can be used with pseudo-tags, e.g. "#..." or "@..." to include|exclude
-f STR
--fgrep STR #Same with just string matching
-i
--invert #Inverse -g or -f
/=+===============================+=\
/ : : \
)==: EXECUTION :==(
\ :_______________________________: /
\=+===============================+=/
-b
--bail #Stops at first error
--exit #Calls process.exit() after all tests have run, even if some Node.js tasks are still hanging.
--fail-zero #Exit code 1 if no tests
--allow-uncaught #Allow uncaught exceptions to stop the process.
--dry-run #Reports tests but do not execute any of them
-w #Runs then watches . for additional runs
--watch #Can type "rs" to restart tests
--watch-files GLOB,... #
--watch-ignore GLOB,... #
-S
--sort #Sort test files
--retries NUM #Silently retry tests if failed.
#Only report last failure of a test if all retries failed
#Can also use this.retries(NUM) inside it()
--node-option|-n 'OPT=VAL' #Pass any option to node ...
--check-leaks #Errors if global variables are created
--globals VAR,... #Allow some global vars
/=+===============================+=\
/ : : \
)==: PROGRAMMATIC :==(
\ :_______________________________: /
\=+===============================+=/
BROWSER ==> #See online doc for how to use Mocha in a browser
#Can use mochawesome as a nice HTML reporter.
new Mocha([OPTS]) #MOCHA
#Most OPTS are available and are camelCase
MOCHA.addFile('FILE')->MOCHA #FILE will be require'd(), i.e. cached
MOCHA.files #'FILE'_ARR
MOCHA.run(FUNC(NUM))->RUNNER #NUM is number of failed tests
MOCHA.options #OPTS.
MOCHA.OPT(VAL)->MOCHA #Sets MOCHA.options.OPT = VAL
#Some OPT names are slightly different, e.g. MOCHA.reporter(REPORTER, REPORTER_OPTS)
GULP-MOCHA([OPTS]) #Executes Mocha tests (5.0.0)
mocha-phantomjs FILE|URL #Command line (Node module)
#Run mocha on HTML file using PhantomJS
#HTML page should replace mocha.run() by:
# if (window.mochaPhantomJS){mochaPhantomJS.run();}else{mocha.run();}
-R MODULE #Reporter.
#Some reporters based on Node.js modules will not work (since it is run in browser),
#e.g. "html-cov"
-C|--no-color #
-t NUM #Test startup timeout
-A USERAGENT #
-c COOKIE_FILE #
-h HEADER_VAR=VAL #
-s WEBPAGE.SETTINGSVAR=VAL #
-v WIDTHxHEIGHT #
GULP-MOCHA-PHANTOMJS(OBJ) ##OBJ:
## - reporter STR
## - mocha OBJ
## - dump FILE (redirected output)
##Client-side page must do (instead of mocha.run()):
## if ( window.mochaPhantomJS ) { mochaPhantomJS.run() } else { mocha.run() }
##Version 0.6.1
/=+===============================+=\
/ : : \
)==: REPORTING :==(
\ :_______________________________: /
\=+===============================+=/
-c|C
--[no-]colors #
--full-trace #Show stack trace
ERROR.expected|actual #If defined, many reporters will show a diff
--no-diff #Do not show diff
--inline-diffs #Show diffs in a more compact way
/=+===============================+=\
/ : : \
)==: SPEED :==(
\ :_______________________________: /
\=+===============================+=/
-t NUM #Test case timeout (def: 2000) (0 for none)
--timeout NUM #Can also use this.timeout(NUM) inside it|before[Each]|describe()
--no-timeouts #Same as -t 0
#Implied by --inspect
-s NUM #Test case slow threshold (def: 75) (in ms).
--slow NUM #Slow test cases can be highlighted by REPORTER
/=+===============================+=\
/ : : \
)==: PARALLELISM :==(
\ :_______________________________: /
\=+===============================+=/
CPU PARALLELISM ==> #The libraries below do not spawn new processes, i.e. only one event loop is used.
#I.e. only one CPU core is used.
#I did not find libraries that offer multiprocessing.
#But they can still be useful with long I/O bound tests.
-p|--parallel #One process per test file
#ENVVAR MOCHA_WORKER_ID is set
-j|--jobs NUM #Def: number of CPU cores - 1
/=+===============================+=\
/ : : \
)==: LINTING :==(
\ :_______________________________: /
\=+===============================+=/
VERSION ==> ##Module 'eslint-plugin-mocha' (10.2.0)
mocha/no-mocha-arrows ##Avoid arrow functions with describe|it|before|after[Each]()
mocha/prefer-arrow-callback [OBJ]##Override of ESLint core rule (which should be disabled), which ignores
##non-arrow functions with describe|it|before|after[Each]()
mocha/no-global-tests ##it() should be inside describe()
mocha/no-nested-tests ##it() should not be inside another it()
mocha/max-top-level-suites [OBJ] ##Max OBJ.limit NUM (def: 1) describe() per file
mocha/no-setup-in-describe ##describe() should only contain it|before|after[Each](), not other code
##Avoid this rule when using data-driven testing
mocha/no-async-describe ##describe() should not contain async FUNC
mocha/no-identical-title ##Avoid duplicated STR for two it|describe()
mocha/ ##Matches REGEXP against describe|it() STR
valid-suite|test-description ##'FUNC'_ARR is function names "describe|it|etc."
['REGEXP'] ['FUNC'_ARR] [STR2] ##STR2 is custom error message
mocha/no-empty-description [OBJ] ##Description cannot be empty STR
##OBJ:
## - testNames STR_ARR
## - message 'ERROR'
mocha/no-hooks [OBJ] ##Avoid before|after[Each]()
##OBJ: allow 'FUNC'_ARR
mocha/no-hooks-for-single-case ##Avoid before|after[Each]() if there is only one it()
[OBJ] ##OBJ: allow 'FUNC'_ARR
mocha/no-sibling-hooks ##Only one before|after[Each]() per describe()
mocha/no-top-level-hooks ##before|afterEach() should be inside describe()
mocha/handle-done-callbacks [OBJ]##If an async FUNC2 was defined, it must be called
##OBJ:
## - ignoreSkipped BOOL (def: false): ignore if it.skip()
mocha/no-return-from-async ##If an async FUNC2 was defined, do not return a value
mocha/no-return-and-callback ##If a callback was defined, do not return a value
mocha/no-synchronous-tests [OBJ] ##Force using async FUNC2, async|await or returning a PROMISE in every test.
##OBJ: allowed STR_ARR among 'callback', 'async', 'promise'
mocha/no-exclusive-tests ##Avoid describe|it.only()
mocha/no-skipped-tests ##Avoid describe|it.skip()
mocha/no-pending-tests ##Avoid it(STR) with no FUNC
mocha/no-exports ##Avoid exporting variables
SETTINGS ##Look for additional function names. OBJ_ARR:
['mocha/additionalCustomNames'] ## - name 'FUNC'
## - can be VARR, including with (), e.g. 'forEach().describeModule'
## - type: 'suite|testCase|hook'
## - interfaces STR_ARR among 'BDD|TDD|QUnit'