Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 166 lines (118 sloc) 8.066 kb
ea7865c @gotwarlost add travis build status
authored
1 ytestrunner [![Build Status](https://secure.travis-ci.org/gotwarlost/ytestrunner.png)](http://travis-ci.org/gotwarlost/ytestrunner)
6b3fa42 @gotwarlost Initial commit
authored
2 ===========
3
7676b59 @gotwarlost updated docs after initial create
authored
4 Run YUI tests for node packages using "npm test" with support for saving test results, coverage and more. Supports YUITest as well as YUI3 style tests.
5
6 To use this module, declare it as a `devDependency` along with the YUI module that you are using for tests (`yui` for yui3 style tests or `yuitest` for standalone yui tests).
7
5894e97 @gotwarlost fix screenshot link in README
authored
8 ![screenshot](http://github.com/gotwarlost/ytestrunner/raw/master/examples/screenshot.png)
6384ff4 @gotwarlost add link to screenshot
authored
9
7676b59 @gotwarlost updated docs after initial create
authored
10 Usage
11 -----
12
13 * Write some code (this module assumes, by default, that code will found at the source root and under `lib/`)
14 * Write tests using a supported format (this module assumes, by default, that tests will be found `test/`)
15 * Modify your `package.json` as follows
16
17 For tests that are implemented using `yuitest`:
18
19 {
20 "devDependencies": {
21 "ytestrunner": "*",
22 "yuitest": "*"
23 },
24 "scripts": {
25 "test": "ytestrunner <other-args>"
26 }
27 }
28
29 For tests in YUI3 module format that are implemented using the `Y.Test` object from `yui` use:
30
31 {
32 "devDependencies": {
33 "ytestrunner": "*",
34 "yui": "*"
35 },
36 "scripts": {
37 "test": "ytestrunner --yui3 <other-args>"
38 }
39 }
40
41 * To run your tests, just type:
42
43 `$ npm test`
44
45 in the folder that has your `package.json` file
46
47 The `ytestrunner` script will run all tests and store results and coverage, if requested.
48
49 Command line options
50 ---------------------
51
52 Usage: ytestrunner <options>
53
54 Basic options
55 --root <dir> : the source root (default: .)
56 --yui3 : flag that enables the YUI3 test harness rather than the YUITest harness
57 --verbose, -v : run tests and instrumentation in verbose mode
58 --help, -h : print this message
59 --tmp <dir> : tmp directory under which instrumented files will be written
60 (default: /tmp)
61 --colors : show colored output (use --no-colors to disable)
62
63 Tests and results
64 --include <pattern> : include file patterns for test files
65 (default: [test/**/*.js, tests/**/*.js])
66 --exclude <pattern> : exclude file patterns for test files
67 (default: [ empty ])
68 --save-results : save results to disk
69 --results-format <format> : results file format
70 --results-file <name> : basename of results file without extension
2b69518 @gotwarlost Update help text in README to match new options; up version
authored
71 (default: results)
7676b59 @gotwarlost updated docs after initial create
authored
72
73 Instrumentation and coverage
74 --coverage, -c : enable instrumentation and coverage stats
2b69518 @gotwarlost Update help text in README to match new options; up version
authored
75 --istanbul : use istanbul instead of YUI coverage for instrumentation and coverage stats
7676b59 @gotwarlost updated docs after initial create
authored
76 --fast-cover : skip source coverage if a newer instrumented file found from previous run
77 --cov-include <pattern> : include file patterns for JS files to be instrumented
2b69518 @gotwarlost Update help text in README to match new options; up version
authored
78 (default: [**/*.js])
7676b59 @gotwarlost updated docs after initial create
authored
79 --cov-exclude <pattern> : exclude file patterns for instrumentation
2b69518 @gotwarlost Update help text in README to match new options; up version
authored
80 (default: [test/**/*.js, tests/**/*.js, **/.*, **/node_modules/**])
7676b59 @gotwarlost updated docs after initial create
authored
81 --save-coverage : save JSON coverage information to disk
82 --coverage-file <name> : basename of JSON coverage file without extension
2b69518 @gotwarlost Update help text in README to match new options; up version
authored
83 (default: coverage/test-coverage)
7676b59 @gotwarlost updated docs after initial create
authored
84 --coverage-report-format <format> : format of coverage report (default: lcov)
85
2b69518 @gotwarlost Update help text in README to match new options; up version
authored
86
87 In addition, the environment variable [ytestopts] can be set with override options.
88 These take precedence over the options passed to command line.
7676b59 @gotwarlost updated docs after initial create
authored
89
90 Using this module effectively
91 -----------------------------
92
93 The module is designed so that it can provide test results and coverage information without having to write any files under your source tree. Saving results and coverage information to disk must be asked for explicitly.
94
95 This allows you to have a simple command in your `package.json` (e.g. `ytestrunner` or `ytestrunner -c` for default coverage) and yet have an automated build set the `ytestopts` environment variable to control writing of results and coverage in supported formats.
96
97 Use of `ytestopts` is also useful during development. If you want to just run one test, say, `foo.test.js` and instrument only one file, say, `foo.js` you could set `ytestopts` thus:
98
99 $ export ytestopts="--include=test/foo.test.js --cov-include=lib/foo.js"
100 $ npm test
101
102
103 This strategy requires no changes to `package.json` and yet will only instrument your source under test and run only one test file.
104
105 Also, keep in mind that boolean options can be negated. So, if your `test` script says `ytestrunner -c` and you are not interested in coverage, you could set `ytestopts` to `--no-coverage` to disable coverage.
106
107 Examples
108 --------
109
110 See the strawman examples in the directories yuitest-sample and yui3-test-sample. Run `npm install` and `npm test` in either of those directories.
111
112 A word on code coverage
113 -----------------------
114
115 Code coverage is implemented as follows:
116
117 * Create an instrumented version of all JS files matching the coverage filters somewhere under `/tmp`. This is done using the `yuitest-coverage` java module.
118 * Hook the module loader to serve the instrumented content at `require` time when the original file is requested. This step is skipped for a file if the coverage module reports an error when instrumenting it.
119 * Collect stats from the global coverage object created by the instrumented code at the end of all tests
120 * Save coverage information and write reports if requested using the `yuitest-coverage-report` java module
121
122 Debugging test execution
123 ------------------------
124
125 The `-v` option is your friend.
126
127 Caveats and known issues
128 ------------------------
129
130 * This module must *not* be globally installed. Even though it uses a YUI test library as part of its runtime execution, it does *not* declare dependencies on these. The caller is responsible for declaring this module as well as the test library used as `devDependencies`. This strategy ensures that this module uses the same instance of the testing library that your tests use.
131 * For the same reason, this module may *not* be npm-linked into your package either, since linked modules cannot "see" other dependencies under your `node_modules/` folder.
132 * A modern `java` is required for instrumentation and coverage reports.
133 * Since instrumentation is done by transparently substituting the instrumented file for the original at `require` time, stack traces will refer to original file but the line numbers in the instrumented file and will *not* make sense when code coverage is turned on
134
135 License
136 -------
137
138 ytestrunner is licensed under the [MIT License](http://github.com/gotwarlost/ytestrunner/raw/master/LICENSE).
139
140 Third-party libraries
141 ---------------------
142
143 The following third-party libraries are used by this module:
144
145 * async: https://github.com/caolan/async
146 * colors: https://github.com/Marak/colors.js
147 * fileset: https://github.com/mklabs/node-fileset
148 * mkdirp: https://github.com/substack/node-mkdirp
149 * nopt: https://github.com/isaacs/nopt
150 * resolve: https://github.com/substack/node-resolve
151 * nodeunit: https://github.com/caolan/nodeunit (dev dependency for unit tests of this module)
152
153 and enables running tests supported by these libraries:
154
155 * YUITest: https://github.com/yui/yuitest
156 * YUI: https://github.com/yui/
157
158 Credits
159 -------
160
161 * [mfncooper](https://github.com/mfncooper) - for ideas on module loader hooks to support code coverage
162 * [baechul](https://github.com/baechul) - for ideas on standard test running using `Y.Test.Runner`
163 * [nzakas](https://github.com/nzakas) - test loading strategy for `YUITest` tests heavily influenced by command line support in that module
164 * [davglass](https://github.com/davglass) - for review of this module
165
Something went wrong with that request. Please try again.