README.md

Tired of testing? Yeti can help.

Yeti automates tests written for various test frameworks.
Yeti scales from your dev box (where it works by itself)
to your CI system (where it launches browsers with Selenium)
without changing your existing tests.

Features

Works with the frameworks you already use.

Automates tests without any additional software. Selenium not required!

Exit status codes

Yeti exits automatically when all tests complete. If test failures occur, Yeti will exit with a non-zero status code.

0 indicates testing was completed and all tests passed.

1 indicates an error occurred that prevented testing from running to completion.

3 indicated testing was completed but some tests failed.

These codes are useful for using Yeti programmatically. The codes 0 and 3 indicate testing completion.
If Yeti ended in code 1, you may wish to retry the command to workaround transient errors. This is useful
when using Yeti to launch browsers in CI, which sometimes may fail due to temporary Selenium issues.

JUnit XML output

Yeti can output machine-readable JUnit XML suitable for use in Jenkins with the --junit option.

$ yeti --junit test/*.html > yeti.xml

Yeti will output XML on stdout and status messages on stderr.

When using Yeti several times in the same Jenkins job, it's useful to label tests with a prefix
to distinguish between different Yeti runs after Jenkins merges the reports together. You can
assign this prefix with the --name option.

Yeti instruments all JavaScript files automatically with Istanbul. If you'd prefer to instrument
your JavaScript code with Istanbul as a part of a build step, you can pass --no-instrument
to skip all instrumenting. Yeti will still generate code coverage reports if used with
the --coverage option.

If you'd like to exclude some JavaScript files from instrumenting, you can pass multiple
--instrument-exclude options defining minimatch patterns to exclude.

This makes it really simple to setup an ad-hoc testing lab shared with your team.

Browser launching

You can specify the wd-url option to connect Yeti to a Selenium 2 Hub using the
WebDriver protocol. Specifying one or more caps options will cause Yeti to launch
browsers for the given capabilities over WebDriver.

The basedir option indicates that the directory where .yeti.json lives is
permitted to serve files to the Yeti Hub.

The glob option defines a pattern to search for test files.

These settings let YUI developers simply run yeti inside of the project directory
to run tests. Since all tests in the project match the glob pattern, the yeti
command works for specific components as well as for the entire project.

This configuration can be overridden on the command line. For example, to ignore the
hub setting, you can run Yeti with --no-hub.

Yeti API

You can require("yeti") inside your application to script Yeti for your own use.

Yeti follows Semantic Versioning but is currently at a 0.x.y release. The public API is not stable. There will be changes.

Client-Side Yeti Integration

Yeti typically automates test frameworks, but you can integrate any client-side test or performance framework
into Yeti. Combined with the Yeti API, you can easily build your own automation tools. YUI uses Yeti in this
way to automate performance benchmarks.

Normally Yeti will scan pages in order to find test frameworks. When serving a page to Yeti, you can set
window.stopYetiScan to true to signal that your page will explicitly submit results to Yeti.

When your framework has results and is ready to move to the next page, you can call window.sendYetiResults
with an object containing data to report. This data will be passed through verbatim to the Node.js Yeti API
for further processing in your tool.

Caveats

Platforms

Yeti should work on all platforms supported by Node.js.
It's tested on Linux and OS X.

Serving tests

You must start Yeti's client in the directory you'll be serving tests from. For security reasons, Yeti will reject requests that try to access files outside of the directory you start Yeti in.