Testing

Installation

Use install.packages("animint2",dep=TRUE) or devtools::install_dev_deps("path/to/animint2") to install packages that are Suggested by animint2.

Remote-controlled/headless browser testing is implemented using library(chromote), which requires you to install google chrome (not chromium).

In test-compiler-ghpages.R there is a test which requires special permission to delete and create repositories under the animint-test github organization.

Installing a github token for use locally

On windows the credential manager will by default give you a token, without enough permissions to perform the delete operation. So to create and install a personal access token (not fine-grained, because you probably want access to all of your respositories from your local computer).

• First you need to become a member of the animint-test org (ask tdhock).
• Go to https://github.com/settings/tokens/new and check repo and delete_repo, generate token.
  • Use gitcreds::gitcreds_delete() if necessary to remove the old token, then git bash on windows, git push, a window pops up, click token.
  • Or use credentials::set_github_pat("my-pat") to set the new one.
  • Or (on ubuntu this worked for me) set Sys.setenv(GITHUB_PAT="your_pat", GITHUB_PAT_GITHUB_COM="your_pat") in ~/.Rprofile, note that setting both environment variables are required. GITHUB_PAT is used by credentials package (used by gert), whereas GITHUB_PAT_GITHUB_COM is used by gitcreds package (used by gh).
  • If you get a GitHub API error (401) bad credentials, that probably means your token is expired.
  • for a classic personal access token, try three permissions: repo, workflow, delete_repo.

Then the test case should run locally.

Installing token in github actions

In the context of github actions, we use a fine-grained PAT, for security.

Need to create one every year (1 year is the max expiration).

• go to https://github.com/settings/personal-access-tokens/new
• Resource owner: animint-test
• Repository access: All repositories
• Repository permissions: Administration and Contents: read and write.
• Generate token
• copy token and paste into PAT_GITHUB on https://github.com/animint/animint2/settings/secrets/actions

Note that it is animint2pages_test_repo under animint-test organization (not animint), because we want to limit the damage that a malicious user could do with this token: there are no repos with important data in the animint-test org.

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 categories

There are three test suites, with files in tests/testthat prefixed accordingly:

• CRAN tests are for verifying that the package passes CRAN check. There is a time limit on CRAN so these are mostly just tests from ggplot2.
• renderer tests check whether the DOM contains what we expect, so we use a headless browser (chromote).
• compiler tests check whether the list returned by animint2dir() or animint2pages() contains what we expect.
• test-shiny.R: does need a headless browser but not yet migrated to new chromote testing framework.

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 (remote driver). This object is introduced to the global environment by tests_init() and is an instance of a chromote class.

Reusable functions

We have a collection of functions in testthat/helper-*.R files 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.

chromote

Documentation for testing on chromote: Chromote testing

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

library("testthat")
library("animint2")
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 chromote.
• 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")