Testing

Installation

Make sure you have the correct versions of the testing software! Working versions of firefox, selenium and RSelenium are listed in testthat.R and the working version of phantomjs is listed in wercker.yml.

Quick start

animint2 provides three main functions for testing:

tests_init()
tests_run()
tests_exit()

tests_init() will start up a "remote-controlled" web browser and a local file server. By default, tests_init() will initialize phantomjs, but you should make sure tests pass on Firefox with tests_init("firefox"); tests_run() before pushing changes to GitHub.

Tests adhere to the testthat framework and are automagically performed via TravisCI everytime we push to GitHub. If you want to simulate those tests locally, simply run tests_init(); tests_run().

On Windows machines, these tests work better using Firefox with tests_init("firefox").

Testing philosophy

Tests are designed to verify that both the compiler and renderer work as intended. Testing is relatively easy on the compiler side as we simply check whether the list returned by animint2dir() contains what we expect. To test the renderer, we have to check whether the DOM contains what we expect.

Writing tests

Since 10 Oct 2015 tests are organized into the following categories. Each category is run in a separate entry of the Travis build matrix.

• test-compiler-*.R: do not need a headless browser, since they only test the JSON/CSV files.
• test-renderer1-*.R, etc: do need a headless browser since they test the renderer HTML. For some reason phantomjs stops if these two categories are combined, so the current workaround is to test them separately.
• test-shiny.R: does need a headless browser but for some reason does not work on travis. Make sure this passes on your local machine before merging any PRs.

Accessing the DOM

To access the DOM, simulate user behavior, and control the web browser that renders test plots, we reference a global object named remDr. This object is introduced to the global environment by tests_init() and is an instance of RSelenium's remoteDriver class. A good example of using remDr is the getHTML() function. In this function, we query the current page source and return it as an R object.

Reusable functions

We have a collection of functions that are reused across the testing suite. For example, animint2HTML() is a wrapper around animint2dir() that adds the rendered SVG/HTML to the function output. If you write tests, please try to understand and use these functions so we don't re-invent the wheel.

Debugging workflow 1

When writing a new test, say 'test-new.R', I suggest this workflow:

tests_init("firefox")
tests_run(filter = "new")

If the "new" tests fail, and you want to know why, inject a browser() at the point of interest in 'test-new.R', then do:

devtools::load_all()
tests_run(filter = "new")

This will give you access to the testing environment. If you are using phantomjs, it may be useful to see what's happening with: remDr$screenshot(display = TRUE)

Debugging workflow 2

Start R in the animint/tests directory, then do

library(testthat)
library(animint)
library(RSelenium)
tests_init("firefox")
setwd("testthat")
source("helper-functions.R")

then execute whatever code you want in the test-*.R files.