Getting Started

Installing Scout

Installing Scout is easiest with npm. To install Scout, open your terminal and run the following command:

$ npm install -g scoutjs

This will install scout as a global command line tool. If npm doesn't have the permission to run the install process you will get a long error with this message in the middle:

Please try running this command again as root/Administrator.

In that case, run the install command again with sudo:

$ sudo npm install -g scoutjs

Installing Scout as a project dependency

Scout can also be installed as a local npm dependency. In the root directory of your project, run the following command:

$ npm install scoutjs --save-dev

This will install Scout in the project's node_modules directory. The Scout binary can run from node_modules/.bin/scoutjs.

Even though it is installed with npm, Scout is only a command line tool, not a true node module. In other words: you can't require('scoutjs').

Writing tests

Creating a test file

Scout test files are plain text files, with a .scout extension. Create a new file with your favorite text editor and add the following lines:

open               http://www.google.com/
type               input[name="q"]          this is a test<Enter>
assertMinLength    h3.r                     10

Now save this file as mytest.scout. Enter the following command in your terminal in the directory containing the file to run this test:

$ scout mytest.scout

You should see something like this:

$ scout mytest.scout

  ✓ open              http://www.google.com/                           [271ms]
  ✓ type              input[name="q"]          this is a test<Enter>   [205ms]
  ✓ assertMinLength   h3.r                     10                      [604ms]

PASS: Executed 1 tests in 1119ms

Actions

Let's go over this line-by-line. Every line is an instruction. The first line is an instruction for Scout to open a page with the Google homepage:

open    http://www.google.com/

open is an action and the Google URL is the argument. Not surprisingly, this line instructs Scout to open the URL.

Actions and arguments must be on the same line and must be separated by two or more spaces, or one or more tabs. Aligning them in pretty columns is optional.

The next line is another instruction, this time to type a sequence of keys into the search field:

type    input[name="q"]    this is a test<Enter>

The word type is again the action, but this action takes two arguments: a CSS selector to specify the target element (here an <input name="q"> and the text that need to be typed.

Scout will simulate a user typing the characters in quick sucession. You may have guessed that <Enter> instructs Scout to simulate an enter key. Scout supports a large number of special keys, like <Up>, <Escape> and <Delete>.

Asserts

assertMinLength    h3.r    10

Instructions starting with "assert" are assertions: tests that verify that a certain statement about the page is true. In this case, Scout will check that there are at least 10 <h3 class="r"> elements visible on the page.

Internally, actions are also assertions and can also fail. For example, the type action will fail when no clickable element matching the selector can be found and open will fail when the URL can't be loaded.

If an assertion or action doesn't immediately pass, Scout will keep on trying until a timeout is reached. Only after an instruction has succeeded will Scout continue with the next. If the timeout is reached, the test fails.

Running tests

Tests are run from the command line:

$ scout filename.scout

Note that test files must have a .scout extension. You can specify as many tests as you like:

$ scout filename1.scout filename2.scout filename3.scout

If you pass a directory name, it will run all of the tests in the directory (even if they are in sub-directories). Files whose names start with an underscore are considered includes and are skipped:

$ scout dirname

You can pass directory names and file names together:

$ scout dirname1 filename1.scout dirname2

Command line options

Besides test names and directory names you can pass a number of options that will alter Scout' default behavior.

--version: Display the version number.
--debug: Write console.log() calls made in the browser as well as any JavaScript errors to the terminal.
Default off.
--faildump: Dump a screenshot to disk if an action or assertion fails.
Default off.
--passdump: Dump a screenshot to disk if an action or assertion passes. Warning: this makes running tests very slow.
Default off.
--color: Logs everything in pretty colors to the terminal. If your terminal does not support this things might get ugly.
Default off.
--parallel=<number>: Set the number of tests that will be run in parallel.
Default 1.
--timeout=<number>: Set the time (in milliseconds) Scout will retry actions and assertions before giving up.
Default 5000.
--step=<number>: Set the time (in milliseconds) between two retries.
Default 10.
--reformat: Skips running any tests, but outputs neatly formatted tests file to the console. See Formatting tests.
--newdumps: Replaces all PNGs that are used as a comparison base by assertResembles. Useful for setting a new baseline after a design change.
Default off.

Command line options can be combined:

$ scout filename.scout --debug --color --timeout=1000

Getting started