UNPKG

6.79 kBMarkdownView Raw
1# node-tap
2
3A <abbr title="Test Anything Protocol">TAP</abbr> test framework for
4Node.js.
5
6[![Build Status](https://travis-ci.org/tapjs/node-tap.svg?branch=master)](https://travis-ci.org/tapjs/node-tap)
7
8_Just wanna see some code? [Get started!](http://www.node-tap.org/basics/)_
9
10It includes a command line test runner for consuming TAP-generating
11test scripts, and a JavaScript framework for writing such scripts.
12
13* [Getting started guide](http://www.node-tap.org/basics/)
14* Built-in [test coverage](http://www.node-tap.org/coverage/)
15* Many [reporter formats](http://www.node-tap.org/reporting/)
16* Extensive [API](http://www.node-tap.org/api/) featuring:
17 * Great [promise support](http://www.node-tap.org/promises/)
18 * Comprehensive [assert library](http://www.node-tap.org/asserts/)
19 * Other [advanced stuff](http://www.node-tap.org/advanced/)
20 * Mocha-like [BDD DSL](http://www.node-tap.org/mochalike/)
21 * [Parallel Testing](http://www.node-tap.org/parallel/)
22* [Command-line interface](http://www.node-tap.org/cli/) for running
23 tests (whether they use node-tap or not)
24
25See [the changelog](http://www.node-tap.org/changelog/) for recent updates, or just get
26started with [the basics](http://www.node-tap.org/basics/).
27
28All this is too much to manage in a single README file, so head over
29to [the website](http://www.node-tap.org/) to learn more.
30
31## Why TAP?
32
33Why should you use this thing!? **LET ME TELL YOU!**
34
35Just kidding.
36
37Most frameworks spend a lot of their documentation telling you why
38they're the greatest. I'm not going to do that.
39
40### <i lang="it">tutti i gusti sono gusti</i>
41
42Software testing is a software and user experience design challenge
43that balances on the intersection of many conflicting demands.
44
45Node-tap is based on [my](http://izs.me) opinions about how a test
46framework should work, and what it should let you do. I do _not_ have
47any opinion about whether or not you share those opinions. If you do
48share them, you will probably enjoy this test library.
49
501. **Test files should be "normal" programs that can be run
51 directly.**
52
53 That means that it can't require a special runner that
54 puts magic functions into a global space. `node test.js` is a
55 perfectly ok way to run a test, and it ought to function
56 exactly the same as when it's run by the fancy runner with
57 reporting and such. JavaScript tests should be JavaScript
58 programs; not english-language poems with weird punctuation.
59
602. **Test output should be connected to the structure of the
61 test file that is easy to determine.**
62
63 That means not unnecessarily deferring test functions
64 until `nextTick`, because that would shift the order of
65 `console.log` output. Synchronous tests should be synchronous.
66
673. **Test files should be run in separate processes.**
68
69 That means that it can't use `require()` to load test files. Doing
70 `node ./test.js` must be the exact same sort of environment for the
71 test as doing `test-runner ./test.js`. Doing `node test/1.js; node
72 test/2.js` should be equivalent (from the test's point of view) to
73 doing `test-runner test/*.js`. This prevents tests from becoming
74 implicitly dependent on one anothers' globals.
75
764. **Assertions should not normally throw (but throws MUST be handled
77 nicely).**
78
79 I frequently write programs that have many hundreds of
80 assertions based on some list of test cases. If the first failure
81 throws, then I don't know if I've failed 100 tests or 1, without
82 wrapping everything in a try-catch. Furthermore, I usually want to
83 see some kind of output or reporting to verify that each one
84 actually ran.
85
86 Basically, it should be your decision whether you want to throw or
87 not. The test framework shouldn't force that on you, and should
88 make either case easy.
89
905. **Test reporting should be separate from the test process, included
91 in the framework, and enabled by default for humans.**
92
93 The [raw test output](http://www.node-tap.org/tap-format/) should
94 be machine-parseable and human-intelligible, and a separate process
95 should consume test output and turn it into a [pretty summarized
96 report](http://www.node-tap.org/reporting/). This means that test
97 data can be stored and parsed later, dug into for additional
98 details, and so on. Also: nyan cat.
99
1006. **Writing tests should be easy, maybe even fun.**
101
102 The lower the barrier to entry for writing new tests, the more
103 tests get written. That means that there should be a relatively
104 small vocabulary of actions that I need to remember as a test
105 author. There is no benefit to having a distinction between a
106 "suite" and a "subtest". Fancy DSLs are pretty, but more to
107 remember.
108
109 That being said, if you return a Promise, or use a DSL that
110 throws a decorated error, then the test framework should Just Work
111 in a way that helps a human being understand the situation.
112
1137. **Tests should output enough data to diagnose a failure, and no
114 more or less.**
115
116 Stack traces pointing at JS internals or the guts of the test
117 framework itself are not helpful. A test framework is a serious UX
118 challenge, and should be treated with care.
119
1208. **Test coverage should be included.**
121
122 Running tests with coverage changes the way that you think about
123 your programs, and provides much deeper insight. Node-tap bundles
124 [nyc](https://istanbul.js.org/) for this.
125
126 It's not enabled by default only because it _does_ necessarily
127 change the nature of the environment a little bit. But I strongly
128 encourage [enabling coverage](http://www.node-tap.org/coverage/).
129
1309. **Tests should be output in a predictable order.**
131
132 Even if they are run in parallel, the test _output_ should be
133 consistent.
134
135 As of version 10, tap supports [parallel
136 tests](http://www.node-tap.org/parallel/), which
137 can make your tests run significantly faster if they are I/O bound
138 or if you have multiple cores on your machine. However, even when
139 run in parallel, the output is still serialized.
140
14110. **Tests should not require more building than your code.**
142
143 Babel and Webpack are lovely and fine. But if your code doesn't
144 require compilation, then I think your tests shouldn't either.
145 Tap is extremely
146 [promise-aware](http://www.node-tap.org/promises/), but works on
147 any version of Node.js back to v4.x.
148
149Software testing should help you build software. It should be a
150security blanket and a quality ratchet, giving you the support to
151undertake massive refactoring and fix bugs without worrying. It
152shouldn't be a purification rite or a hazing ritual.
153
154There are many opinions left off of this list! Reasonable people can
155disagree. But if you find yourself nodding along, [maybe tap is for
156you](http://www.node-tap.org/basics/).