Permalink
Browse files

Initial commit

  • Loading branch information...
akaspin committed Oct 27, 2010
0 parents commit e5e2028a66a9f6b3ab7a893c5b698ca360c38e8c
Showing with 668 additions and 0 deletions.
  1. +2 −0 .gitignore
  2. +10 −0 Makefile
  3. +241 −0 readme.md
  4. +369 −0 run.js
  5. +14 −0 test/pit/test-chain.js
  6. +6 −0 test/pit/test-marks.js
  7. +7 −0 test/simple/test-fail-out.js
  8. +6 −0 test/simple/test-fail.js
  9. +7 −0 test/simple/test-pass-out.js
  10. +6 −0 test/simple/test-pass.js
@@ -0,0 +1,2 @@
+/.project
+/.settings
@@ -0,0 +1,10 @@
+NODE=`which node`
+THIS_DIR=$(shell pwd)
+
+default: test
+
+test:
+ @$(NODE) run.js test/pit
+ @$(NODE) run.js test/simple
+
+.PHONY: test
241 readme.md
@@ -0,0 +1,241 @@
+# pit
+
+Simple drop-in test runner for [node.js](http://nodejs.org/).
+
+Test matters. But use of big testing frameworks leads developer to loss of
+control. *node.js* is asynchronous thing, and lots of errors may dissappear
+in the bowels of next big test system.
+
+*pit* is one small (about 10k) `js` file. No installations, no dependencies, no
+loss of control.
+
+## Basic usage
+
+As mentioned earlier, each test is simple node.js application. *pit* just
+collects tests and runs they. If app throws exception - test fails. That's all.
+
+Simply put `run.js` wherever you want and and pit it on your tests. For example,
+we have the following directory structure:
+
+ + app
+ - test-feature.js <- Put some to STDOUT
+ - test-report.js <- This test must fail and brings some to STDOUT
+ - test-simple.js <- Simple. Must pass
+ - test-unstable.js <- This test must fail
+ - run.js <- Yes, its me!
+ - index.js
+
+... and we in app directory...
+
+ $node test/run.js
+
+... and ...
+
+ PASS feature
+ * output:
+ Just bring something
+ FAIL report
+ * output:
+ Just some output
+ * errors:
+ node.js:50
+ throw e; // process.nextTick error, or 'error' ...
+ ^
+ AssertionError: true == false
+ ...
+ FAIL unstable
+ * errors:
+ node.js:50
+ throw e; // process.nextTick error, or 'error' ...
+ ^
+ AssertionError: true == false
+ ...
+
+ 2/3
+
+Fast clean and effective. *pit* collect all `test-*.js` files from current
+directory and run each as separate process. If test throws exception - it fails.
+Passed tests that that not print not appear in the log by default, but will be
+counted in the total result.
+
+## Advanced usage
+
+You can control many things with parameters. *pit* takes two types of
+parameters: options and directories.
+
+ node run.js [--option ...] [directory ...]
+
+All parameters separates by space. Options are preceded by double dash (`--`).
+Directories... just write it. Order of options and directories is not
+important.
+
+### Directories, prefixes, extensions and host interpreter
+
+Current dir is cool. But *pit* can collect the tests of those directories that
+you specify. Note that *pit* is not looking in the directories recursively.
+
+ node run.js ../../other-dir tests tests/basic tests/advanced
+
+By default *pit* searches for files with names `test-*.js` and runs they with
+`node`. This behavior can be changed using options `prefix`, `ext` and `host`.
+
+ node run.js --prefix=bench- --ext=.pl --host=perl
+
+This may seem redundant, but may prove to be useful.
+
+### Concurrency
+
+As stated above, *pit* runs each test in separate process one after another.
+You can increase the number of concurrent tests by option `conc`.
+
+ node run.js --conc=4
+
+### Customising output
+
+By default, *pit* following the next rules:
+
+* If test *passed* and nothing is printed, it will not appear in the log but
+ will be counted in the total result.
+* If test *passed* but prints some in `STDOUT`,
+ it will appear in the log with output.
+* If test failed, it will appear in the log with
+ it's `STDERR` and `STDOUT` (if exists).
+* Regardless any options, all tests will be counted in the total result.
+
+You can change it with next secret weapons: `noout`, `noerr`, `passed` and
+`nofail`.
+
+`noout` and `noerr` disables test's `STDOUT` and `STDERR` respectively. With
+`noout` option *pit* logs only failed tests. With `noerr` option *disables*
+tests `STDOUT` but failed tests will be appeared in log.
+
+ $node test/run.js --noout --noerr
+
+ FAIL report
+ FAIL unstable
+
+ 2/3
+
+To disable log completelly and get only total results you need add `nofail`
+option to `noerr` and `noout`.
+
+ $node test/run.js --noout --noerr --nofail
+ 2/3
+
+`passed` option forces *pit* to log passed tests regardless their `STDOUT`.
+
+ $node test/run.js --noout --noerr --passed
+
+ PASS feature
+ FAIL report
+ PASS simple
+ FAIL unstable
+
+ 2/3
+
+### Timing
+
+*Pit* also has very basic benchmarking ability. It can be done with `times`
+option.
+
+ $node test/run.js --noout --noerr --passed --times
+
+ PASS feature (0.069s)
+ FAIL report (0.088s)
+ PASS simple (0.072s)
+ FAIL unstable (0.087s)
+
+ 2/3 (0.178s)
+
+*Pit* measures duration of each test in seconds - from start to end. Also *pit*
+measures total duration. Of course, total duration depends from `conc` option.
+
+## Helpers
+
+*Pit* written to run tests. But it has three convenient tool for creating them.
+These tools are `expect`, `mark` and `hook`.
+
+### expect and mark
+
+`expect` function give you the ability to determine - what is expected from
+the test. `mark` help meet its needs.
+
+For example, running this test...
+
+ var pit = require('./run.js');
+
+ pit.expect(5); // Set five expected "common" marks
+ pit.expect("be-exp", 1); // Set one expected "be-exp" mark
+ pit.mark("not-exp"); // Put "not-exp" mark
+ pit.mark("be-exp"); // Put "be-exp" mark
+
+... will give the following result
+
+ FAIL marks
+ * errors
+ assert.js:80
+ throw new assert.AssertionError({
+ ^
+ AssertionError: Marks do not meet expectations:
+ - common: 0/5 <- Expected but not satisfied
+ + be-exp: 1/1 <- Satisfied
+ - not-exp: 1/undefined <- Unexpected mark
+ ...
+
+`expect` sets expected number of marks. It takes two arguments: mark label and
+expected number. Invoking `expect` with one argument causing set number of
+"common" mark.
+
+Marks can be increased by `mark` function. Being called with single parameter -
+the mark's label, it increases mark's value. Without any parameters `mark`
+increases value of "common" mark.
+
+### hook
+
+When invoked at least once `expect` and `mark` causes hanging a handler to
+`process->exit` event. If you want to add yours, use `hook`. Small example:
+
+ var pit = require('./run.js');
+ var simpleMessage = "Hook";
+
+ pit.hook(function(marks, expects) {
+ console.log("%s three. Will not displayed", simpleMessage);
+ });
+ pit.hook(function(marks, expects) {
+ console.log("%s two", simpleMessage);
+ throw "ARRR!";
+ });
+ pit.hook(function(marks, expects) {
+ console.log("%s one", simpleMessage);
+ });
+
+... and output:
+
+ FAIL chain
+ * output
+ Hook one <- hook one
+ Hook two <- hook two
+ * errors
+ /home/dev/pit/test-chain.js:9 <- Ohh!
+ throw "ARRR!";
+ ^
+ ARRR!
+
+*Hooks* are executed in stacked (FILO) order. The default handler runs at last.
+Exceptions interrupts execution.
+
+`hook` takes one parameter - hook function. Which in turn takes two parameters:
+collected marks and expects. Which have the following structure:
+
+ {
+ <mark label>: <{int}number of marks>,
+ ...
+ }
+
+## Need help?
+
+Call *pit* with `help` option:
+
+ node run.js --help
+
+You can also look at examples in "test" directory and run all by `make`.
Oops, something went wrong.

0 comments on commit e5e2028

Please sign in to comment.