Visual test system instructions

Visual test system instructions

This is a primer on how to download and the visual test code.

System requirements:

• ImageMagick, to do image comparisons
• Ghostscript, to convert from PDF to PNG (ImageMagick's convert function apparently uses Ghostscript to do this conversion but I had weird color consistency problems with it).
• If you have ImageMagick installed, without a separate Ghostscript installation, you can use IM's convert utility by setting a flag in the convert_pdf2png function (this will be easier in the future).

I don't know if this will work on Windows right now -- it's possible I've handled path names and done other things that work only on Unixlike systems. If you try this on Windows, please let me know what works and doesn't work.

Also see the Visual test system overview page for further information.

Get the code

First, grab the branch. From the command line:

# Download the branch and check it out
git fetch https://github.com/wch/ggplot2 visual-test
git checkout FETCH_HEAD

# Create a new branch here called vtest
git checkout -b vtest

All the new test-related functions are in R/visual-test.r, and the test scripts are in visual_test/.

Run visual tests

In the ggplot2 directory, start up R. At the moment, the test functions have to be run from the top level ggplot2/ directory.

library(devtools)
dev_mode()
load_all(".")

Not all of the test scripts work right now - some throw errors, which the test system doesn't handle yet.

# Presently can't run all tests using vtest()
# These particular test sets work:
vtest('aspect-ratio')
vtest('dotplot')

# Make webpages for all the completed tests.
# It also prints a message with the path to the index.html file.
vtest_webpage()

That generates the test images, and puts web pages in visual_test/html/. This directory is ignored by git, using a .gitignore file.

Commit test results

At this point you can commit the test results to the git repo on this branch.

git add visual_test/aspect-ratio visual_test/dotplot
git commit -m "Add visual test results"

Make changes

Now you can make changes that will result in different test images. You can modify the code for the visual tests. You can also add, remove, or rename them. Or if you're serious, you can edit "real" ggplot2 code. :)

After you make the changes, re-run the tests:

# ... edit code ...

vtest('aspect-ratio')
vtest('dotplot')

See what changed

Finally, the fun part, finding out what changed:

# Print out what changed
vdiffstat()

# Generate webpages showing what changed
vdiff_webpage()

That generates the visual diff results, and puts web pages in visual_test/diff/. This directory is ignored by git via .gitignore.

If you added or removed any tests and want to commit them:

# Add test image
git add visual_test/xxx/yyy.pdf

# Remove test image
git rm visual_test/xxx/yyy.pdf

Clean up

At the end, you can clean up and delete the branch. You may have to separately delete the visual_test directory.

# All done: delete the test branch
git checkout master
git branch -D vtest