tapjs · Jun 24, 2016 · Jun 24, 2016 · Jun 24, 2016 · Jun 24, 2016 · Jun 24, 2016
Showing 491 changed files with 41,064 additions and 9,920 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,11 @@
+# Set the default behavior, in case people don't have core.autocrlf set
+* text=auto
+
+# Require Unix line endings
+* text eol=lf
+
+# Denote all files that are truly binary and should not be modified.
+*.png binary
+*.jpg binary
+*.ico binary
+*.gif binary
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [isaacs]
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,25 @@
-node_modules/
-coverage/
-.nyc_output/
-nyc_output/
+/*
+/.*
+
+!bin/
+!lib/
+!docs/
+/docs/public
+/docs/node_modules
+/docs/.cache
+!package.json
+!package-lock.json
+!README.md
+!CONTRIBUTING.md
+!LICENSE
+!CHANGELOG.md
+!example/
+!scripts/
+!tap-snapshots/
+!test/
+!.travis.yml
+!.gitignore
+!.gitattributes
+!coverage-map.js
+!postpublish.sh
+!netlify.toml
diff --git a/.travis.yml b/.travis.yml
@@ -1,8 +1,16 @@
-sudo: false
 language: node_js
+
 node_js:
-  - '0.10'
-  - '0.12'
-  - '4'
-  - '5'
-  - '6'
+  - 12
+  - 10
+  - 8
+
+os:
+  - linux
+
+cache:
+  directories:
+    - $HOME/.npm
+
+notifications:
+  email: false
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,138 +1,2 @@
-## 5.4
-
-Support passing in a class to `t.throws`, rather than an Error
-sample object.
-
-## 5.3
-
-Return a `Promise` object from `t.test()`, `t.spawn()`, and
-`t.stdin()`.
-
-## 5.2
-
-Adds `t.beforeEach()` and `t.afterEach()`.
-
-## 5.1
-
-All about the cli flags!
-
-Support `--node-arg=...` and `--nyc-arg=...` command line flags.
-
-Add support for coverage checking using `--statements=95` etc.
-
-Test for executable-ness more consistently across platforms.
-
-## 5.0
-
-Make it impossible to `try/catch` out of plan/end abuses.  Calling
-`t.end()` more than once, or having a number of tests that doesn't
-match the `plan()` number, is always a failure.
-
-Push thrown errors to the front of the action queue.  This means that,
-even if other things are pending, an uncaught exception or a plan/end
-bug, will always take the highest priority in what gets output.
-
-Many updates to nyc, spawn-wrap, and foreground-child, so that tap now
-reliably works on Windows (and a [ci to prove
-it](https://ci.appveyor.com/project/isaacs/node-tap).)
-
-Moved into the [tapjs org](https://github.com/tapjs).
-
-## 4.0
-
-Raise an error if `t.end()` is explicitly called more than once.  This
-is a breaking change, because it can cause previously-passing tests to
-fail, if they did `t.end()` in multiple places.
-
-Support promises returned by mochalike functions.
-
-## 3.1
-
-Support sending coverage output to both codecov.io and coveralls.io.
-
-## 3.0
-
-Upgrade to nyc 5.  This means that `config.nyc.exclude` arrays in
-`package.json` now take globs instead of regular expressions.
-
-## 2.3
-
-Use the name of the function supplied to `t.test(fn)` as the test name
-if a string name is not provided.
-
-Better support for sparse arrays.
-
-## 2.2
-
-Add support for Codecov.io as well as Coveralls.io.
-
-Catch failures that come after an otherwise successful test set.
-
-Fix timing of `t.on('end')` so that event fires *before* the next
-child test is started, instead of immediately after it.
-
-`t.throws()` can now be supplied a regexp for the expected Error
-message.
-
-## 2.1
-
-Exit in failure on root test bailout.
-
-Support promises returned by `t.test(fn)` function.
-
-## 2.0
-
-Update matching behavior using [tmatch](http://npm.im/tmatch).  This
-is a breaking change to `t.match`, `t.similar`, `t.has`, etc., but
-brings them more in line with what people epirically seem to expect
-these functions to do.
-
-Deal with pending handles left open when a child process gets a
-`SIGTERM` on timeout.
-
-Remove domains in favor of more reliable and less invasive state and
-error-catching bookkeeping.
-
-## 1.4
-
-Add `t.contains()` alias for `t.match()`.
-
-Use `deeper` for deep object similarity testing.
-
-Treat unfinished tests as failures.
-
-Add support for pragmas in TAP output.
-
-## 1.3
-
-Bind all Test methods to object.
-
-Add `t.tearDown()`, `t.autoend()`, so that the root export is Just
-Another Test Object, which just happens to be piping to stdout.
-
-Support getting an error object in bailout()
-
-## 1.2
-
-Better support for exit status codes.
-
-## 1.1
-
-Add coverage using nyc.
-
-If a `COVERALLS_REPO_TOKEN` is provided, then run tests with coverage,
-and pipe to coveralls.
-
-## 1.0
-
-Complete rewrite from 0.x.
-
-Child tests implemented as nested TAP output, similar to Perl's `Test::More`.
-
-## 0.x
-
-The 0.x versions used a "flattened" approach to child tests, which
-requires some bookkeeping.
-
-It worked, mostly, but its primary success was inspiring
-[tape](http://npm.im/tape) and tap v1 and beyond.
+Please see [the tap website](http://www.node-tap.org/changelog/) for
+the curated changelog.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,15 +1,13 @@
-- Check the [issues](https://github.com/taprc/node-tap/issues) to see
+Please consider signing [the neveragain.tech pledge](http://neveragain.tech/)
+
+- Check the [issues](https://github.com/tapjs/node-tap/issues) to see
   stuff that is likely to be accepted.
 - Every patch should have a new test that fails without the patch and
   passes with the patch.
-- All tests should pass on Node 0.8 and above.  If some tests have to
-  be skipped for very old Node versions that's fine, but the
-  functionality should still work as intended.
-- Run `npm run regen-fixtures` to re-generate the output tests
-  whenever output is changed.  However, when you do this, make sure to
-  check the change to ensure that it's what you intended, and that it
-  didn't cause any other inadvertent changes.
-- Prefer adding cases to an existing test rather than writing a new
-  one from scratch.  For example, add a new test in `test/test/*.js`
-  rather than create a new test that validates test output.
-- Docs should be changed on the `gh-pages` branch
+- All tests should pass on Node 8 and above.  If some tests have to be
+  skipped for very old Node versions that's fine, but the functionality
+  should still work as intended.
+- Run `npm run snap` to re-generate the output tests whenever output is
+  changed.  However, when you do this, make sure to check the change to
+  ensure that it's what you intended, and that it didn't cause any other
+  inadvertent changes.
diff --git a/README.md b/README.md
@@ -3,10 +3,12 @@
 A <abbr title="Test Anything Protocol">TAP</abbr> test framework for
 Node.js.
 
-[![Build Status](https://travis-ci.org/tapjs/node-tap.svg?branch=master)](https://travis-ci.org/tapjs/node-tap) [![Build Status](https://ci.appveyor.com/api/projects/status/913p1ypf21gf4leu?svg=true)](https://ci.appveyor.com/project/isaacs/node-tap) [![Coverage Status](https://coveralls.io/repos/tapjs/node-tap/badge.svg?branch=master&service=github)](https://coveralls.io/github/tapjs/node-tap?branch=master)
+[![Build Status](https://travis-ci.org/tapjs/node-tap.svg?branch=master)](https://travis-ci.org/tapjs/node-tap)
 
-It includes a command line test runner for consuming TAP-generating
-test scripts, and a JavaScript framework for writing such scripts.
+_Just wanna see some code? [Get started!](http://www.node-tap.org/basics/)_
+
+It includes a command line test runner for consuming TAP-generating test
+scripts, and a JavaScript framework for writing such scripts.
 
 * [Getting started guide](http://www.node-tap.org/basics/)
 * Built-in [test coverage](http://www.node-tap.org/coverage/)
@@ -15,8 +17,142 @@ test scripts, and a JavaScript framework for writing such scripts.
   * Great [promise support](http://www.node-tap.org/promises/)
   * Comprehensive [assert library](http://www.node-tap.org/asserts/)
   * Other [advanced stuff](http://www.node-tap.org/advanced/)
-* [Command-line interface](http://www.node-tap.org/cli/) for running
-  tests (whether they use node-tap or not)
+  * Mocha-like [BDD DSL](http://www.node-tap.org/mochalike/)
+  * [Parallel Testing](http://www.node-tap.org/parallel/)
+* [Command-line interface](http://www.node-tap.org/cli/) for running tests
+  (whether they use node-tap or not)
+
+See [the changelog](http://www.node-tap.org/changelog/) for recent updates,
+or just get started with [the basics](http://www.node-tap.org/basics/).
+
+All this is too much to manage in a single README file, so head over to
+[the website](http://www.node-tap.org/) to learn more.
+
+## Why TAP?
+
+Why should you use this thing!?  **LET ME TELL YOU!**
+
+Just kidding.
+
+Most frameworks spend a lot of their documentation telling you why they're
+the greatest.  I'm not going to do that.
+
+### <i lang="it" title="all tastes are tastes">tutti i gusti sono gusti</i>
+
+Software testing is a software and user experience design challenge that
+balances on the intersection of many conflicting demands.
+
+Node-tap is based on [my](http://izs.me) opinions about how a test
+framework should work, and what it should let you do.  I do _not_ have any
+opinion about whether or not you share those opinions.  If you do share
+them, you will probably enjoy this test library.
+
+1. **Test files should be "normal" programs that can be run directly.**
+
+   That means that it can't require a special runner that puts magic
+   functions into a global space.  `node test.js` is a perfectly ok way to
+   run a test, and it ought to function exactly the same as when it's run
+   by the fancy runner with reporting and such.  JavaScript tests should be
+   JavaScript programs; not english-language poems with weird punctuation.
+
+2. **Test output should be connected to the structure of the test file in a
+   way that is easy to determine.**
+
+   That means not unnecessarily deferring test functions until `nextTick`,
+   because that would shift the order of `console.log` output.  Synchronous
+   tests should be synchronous.
+
+3. **Test files should be run in separate processes.**
+
+   That means that it can't use `require()` to load test files.  Doing
+   `node ./test.js` must be the exact same sort of environment for the test
+   as doing `test-runner ./test.js`.  Doing `node test/1.js; node
+   test/2.js` should be equivalent (from the test's point of view) to doing
+   `test-runner test/*.js`.  This prevents tests from becoming implicitly
+   dependent on one anothers' globals.
+
+4. **Assertions should not normally throw (but throws MUST be handled
+   nicely).**
+
+   I frequently write programs that have many hundreds of assertions based
+   on some list of test cases.  If the first failure throws, then I don't
+   know if I've failed 100 tests or 1, without wrapping everything in a
+   try-catch.  Furthermore, I usually want to see some kind of output or
+   reporting to verify that each one actually ran.
+
+   Basically, it should be your decision whether you want to throw or not.
+   The test framework shouldn't force that on you, and should make either
+   case easy.
+
+5. **Test reporting should be separate from the test process, included in
+   the framework, and enabled by default for humans.**
+
+   The [raw test output](https://www.node-tap.org/tap-format/) should be
+   machine-parseable and human-intelligible, and a separate process should
+   consume test output and turn it into a [pretty summarized
+   report](https://www.node-tap.org/reporting/).  This means that test data
+   can be stored and parsed later, dug into for additional details, and so
+   on.  Also: nyan cat.
+
+6. **Writing tests should be easy, maybe even fun.**
+
+   The lower the barrier to entry for writing new tests, the more tests get
+   written.  That means that there should be a relatively small vocabulary
+   of actions that I need to remember as a test author.  There is no
+   benefit to having a distinction between a "suite" and a "subtest".
+   Fancy DSLs are pretty, but more to remember.
+
+   That being said, if you return a Promise, or use a DSL that throws a
+   decorated error, then the test framework should Just Work in a way that
+   helps a human being understand the situation.
+
+7. **Tests should output enough data to diagnose a failure, and no more or
+   less.**
+
+   Stack traces pointing at JS internals or the guts of the test framework
+   itself are not helpful.  A test framework is a serious UX challenge, and
+   should be treated with care.
+
+8. **Test coverage should be included.**
+
+   Running tests with coverage changes the way that you think about your
+   programs, and provides much deeper insight.  Node-tap bundles
+   [NYC](https://istanbul.js.org/) for this.
+
+   It _does_ necessarily change the nature of the environment a little bit.
+   But in this case, it's worth it, and NYC has come a long way towards
+   maintaining this promise.
+
+   Coverage _enforcement_ is not on by default, but I strongly encourage
+   it.  You can put `"tap":{"check-coverage":true}` in your package.json,
+   or pass [`--100`](https://www.node-tap.org/100/) on the command line.
+   In a future version, it will likely be enabled by default.
+
+9. **Tests should not require more building than your code.**
+
+   Babel and Webpack are lovely and fine.  But if your code doesn't require
+   compilation, then I think your tests shouldn't either.  Tap is extremely
+   [promise-aware](https://www.node-tap.org/promises/).  JSX, TypeScript,
+   Flow, and ES-Modules are
+   [built-in](https://www.node-tap.org/using-with/) when tests are run by
+   the tap CLI.
+
+10. **Tests should run as fast as possible, given all the prior
+    considerations.**
+
+   As of version 10, tap supports [parallel
+   tests](https://www.node-tap.org/parallel/).  As of version 13, the test
+   runner defaults to running the same number of parallel tests as there
+   are CPUs on the system.
+
+   This makes tests significantly faster in almost every case, on any machine
+   with multiple cores.
+
+Software testing should help you build software.  It should be a security
+blanket and a quality ratchet, giving you the support to undertake massive
+refactoring and fix bugs without worrying.  It shouldn't be a purification
+rite or a hazing ritual.
 
-All this is too much to manage in a single README file, so head over
-to [the website](http://www.node-tap.org/) to learn more.
+There are many opinions left off of this list!  Reasonable people can
+disagree.  But if you find yourself nodding along, [maybe tap is for
+you](https://www.node-tap.org/basics/).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# These are supported funding model platforms

		github: [isaacs]