1 | # node-tap
|
2 |
|
3 | A <abbr title="Test Anything Protocol">TAP</abbr> test framework for
|
4 | Node.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 |
|
10 | It includes a command line test runner for consuming TAP-generating
|
11 | test 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 |
|
25 | See [the changelog](http://www.node-tap.org/changelog/) for recent updates, or just get
|
26 | started with [the basics](http://www.node-tap.org/basics/).
|
27 |
|
28 | All this is too much to manage in a single README file, so head over
|
29 | to [the website](http://www.node-tap.org/) to learn more.
|
30 |
|
31 | ## Why TAP?
|
32 |
|
33 | Why should you use this thing!? **LET ME TELL YOU!**
|
34 |
|
35 | Just kidding.
|
36 |
|
37 | Most frameworks spend a lot of their documentation telling you why
|
38 | they're the greatest. I'm not going to do that.
|
39 |
|
40 | ### <i lang="it">tutti i gusti sono gusti</i>
|
41 |
|
42 | Software testing is a software and user experience design challenge
|
43 | that balances on the intersection of many conflicting demands.
|
44 |
|
45 | Node-tap is based on [my](http://izs.me) opinions about how a test
|
46 | framework should work, and what it should let you do. I do _not_ have
|
47 | any opinion about whether or not you share those opinions. If you do
|
48 | share them, you will probably enjoy this test library.
|
49 |
|
50 | 1. **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 |
|
60 | 2. **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 |
|
67 | 3. **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 |
|
76 | 4. **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 |
|
90 | 5. **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 |
|
100 | 6. **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 |
|
113 | 7. **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 |
|
120 | 8. **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 |
|
130 | 9. **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 |
|
141 | 10. **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 |
|
149 | Software testing should help you build software. It should be a
|
150 | security blanket and a quality ratchet, giving you the support to
|
151 | undertake massive refactoring and fix bugs without worrying. It
|
152 | shouldn't be a purification rite or a hazing ritual.
|
153 |
|
154 | There are many opinions left off of this list! Reasonable people can
|
155 | disagree. But if you find yourself nodding along, [maybe tap is for
|
156 | you](http://www.node-tap.org/basics/).
|