Testing

Installation

Make sure you have the correct versions of the testing software! We support browser testing with firefox using docker and phantomjs for headless testing. You'll be needing these things installed in your system for both modes:

• RSelenium(v1.7.4), remotes::install_github("ropensci/RSelenium@v1.7.4")
• Animint2

For Headless testing:

• Phantomjs(v2.1.1)

For Real browser testing:

• Docker
• selenium/standalone-firefox-debug:2.53.0 docker image use docker pull selenium/standalone-firefox-debug:2.53.0 to get it downloaded in your system.

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(using servr package). By default, tests_init() will initialize phantomjs, but you should make sure tests pass on Firefox with tests_init("firefox") before pushing changes to GitHub.
• tests_run() runs all tests the on your system. Since it's heavy task to run all tests everytime, you can test a specific thing by passing filter="" in tests_run(). For example, if you want to test a test axis-angle-rotate.R, you would have to run like this: tests_run(filter = "axis-angle-rotate")

Note: 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().

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:

Before you start, make sure to check the following things:

• Installed all needed packages and tools.
• Have docker image as specified on top of this wiki.

For real browser testing:

• Start docker image.

For Linux systems:

docker run -d --network="host" selenium/standalone-firefox-debug:2.53.0

For windows and mac:

docker run -d -p 4444:4444 -p 5900:5900 selenium/standalone-firefox-debug:2.53.0

• Now, Load needed libraries and functions: Start R in animint2/tests directory then run following-

library("testthat")
library("animint2")
library("RSelenium");library("XML")
setwd("testthat")
source("helper-functions.R")
source("helper-HTML.R")
source("helper-plot-data.r")

• Initialize the remote driver:

tests_init("firefox")

You'll get an alert on console to remind you to start docker image(ignore if already done that).

Now you can start testing!

# to run all tests
tests_run() 
# to run specific
tests_run(filter="axis-rotate")
# to run a all renderer tests
tests_run(filter="renderer")

To see what's going on browser inside the docker, download any VNC client and then connect to the docker using port 5900 like localhost:5900 or 127.0.0.1:5900 i.e your localhost url:5900. You'll be able to see what's going in browser and use firefox browser debugger as well.

For headless browser testing:

• Start R in animint2/tests directory then run following-

library("testthat")
library("animint2")
library("RSelenium");library("XML")
setwd("testthat")
source("helper-functions.R")
source("helper-HTML.R")
source("helper-plot-data.r")

• Now, run tests_init(). It'll download and start your phantomjs binary using wdman package.
• Now you can run tests using tests_run().

# to run all tests
tests_run() 
# to run specific
tests_run(filter="axis-rotate")
# to run a all renderer tests
tests_run(filter="renderer")

Building animint2 package from repo directory.

In case you're doing any changes in code of animint2 and want to use the same as library, you can do the following.

• Navigate to the directory where animint2 is located. for ex: /projects/ where inside projects there is animint2.
• Run the following in cli:

R CMD INSTALL animint2

It'll build the package and install in your system.