Developer’s guide¶
Note
This guide assumes you have cloned and built the geojs repository according to the Quick start guide.
To run all of the tests, you will need the optional packages and python modules listed there.
Geojs employs several different frameworks for unit testing. These frameworks have been designed to make it easy for developers to add more tests as new features are added to the api.
Code quality tests¶
All javascript source files included in the library for deployment are
checked against ESLint for uniform styling
and strict for common errors patterns. The style rules for geojs are
located in the .eslintrc
file in the root of the repository. These
tests are preformed automatically for every file added to the build; no
additional configuration is required. You can run a quick check of the
code style outside of CMake by running npm run lint
.
Code coverage¶
Code coverage information is generated automatically for all headless unit tests
by Karma’s test runner when running npm run test
. The coverage information is
submitted to codecov and
cdash after every
successful Travis run.
Headless browser testing¶
Geojs uses PhantomJS for headless browser testing of core utilities. Unfortunately because PhantomJS does not support webgl at this time, so code paths requiring webgl must be either mocked or run in an environment such as xvfb.
The headless unit tests should be placed in the tests/cases/
directory. All javascript files in this directory will be detected
by the Karma test
runner and executed automatically when you run npm run test
. It
is possible to debug these tests in a normal browser as well. Just run
npm run start
and browse to http://localhost:9876/debug.html. The
test runner will automatically rebuild the tests as you modify files
so there is no need to rerun this command unless you add a new file.
There are a number of utilities present in the file tests/test-utils.js
that developers can use to make better unit tests. For example, a mocked
vgl renderer can be used to hit code paths within webgl rendered layers. There
are also methods for mocking global methods like requestAnimationFrame
to test complex, asynchronous code paths in a stable and repeatable manner.
The Sinon testing library is also available to
generate stubs, spies, and mocked methods. Because all tests share
a global scope, they should be careful to clean up all mocking and
instrumentation after running. Ideally, each test should be runnable
independently and use jasmines beforeEach
and afterEach
methods
for setup and tear down.
Headless WebGL testing¶
To fully test code that uses WebGL, a browser with WebGL is required. If xvfb, osmesa, and Firefox are installed, some tests can be run in a virtual frame buffer that doesn’t require a display. May of these tests depend on additional data which can be downloaded by using CMake and running ctest.
For example, running
cmake /path/to/geojs
make
xvfb-run -s '-ac -screen 0 1280x1024x24' ctest -VV -R ffheadless
will run the headless WebGL tests. After the data for tests is downloaded,
the tests can also be run via npm run test-webgl
, which assumes that
xvfb-run
is available.
The headless unit tests that require WebGL should be placed in the
tests/gl-cases/
directory. When tests are run in a normal browser via
npm run start
, the webgl tests are included.
Many of these tests compare against a baseline image. If a test is changed or
added, new baselines can be generated and optionally uploaded via the script
built into test/baseline_images.py
.
If a test fails, the specific test will be reported by the test runner, and the
base and test images are saved in the images
subdirectory of the build
directory. The images have the base name of the test and end in -base.png
for the reference image, -test.png
for the current test, and -diff.png
for a difference image where areas that are different are highlight (using
resemblejs, the default highlight color is pink).
Unless an image comparison test fails, images are not automatically saved. To
save all images, add the environment variable TEST_SAVE_IMAGE=all
to the
test command or set this parameter in CMake.
Note
Typically, CMake is used to build outside of the source tree. This
means you would create a new directory somewhere and point cmake
to the geojs source directory. You may need to rerun cmake
and
make
after making changes to your code for everything to
build correctly. Try running ccmake /path/to/geojs
for a full
list of configuration options.
Examples and tests that need to run in a standard browser should be tested by
creating an entry in the tests/headed-cases/
directory. To run these tests
in a normal browser, run npm run start
and browse to
http://localhost:9876/debug.html?test=all. Since the browser’s direct
screen output is used, the browser must be running on the same machine as the
npm run start
command.
Release Process¶
To make a new GeoJS release:
- Update the version number in package.json.
- Update the CHANGELOG.md file with changes since the last release
- Commit to GitHub and merge to master
- Tag the commit on GitHub with a tag of the form vX.Y.Z (e.g., v0.17.0).
- After the release appears on GitHub, update the release notes with the changes since the last release.
Tagging a commit on the master branch will trigger a build on travis-ci.org, at the end of which the new version will be published to npm and the build artifacts will be pushed to the tagged version on GitHub.