Test Environment
To maintain the quality of the styles in the official repository, we have set up an environment for quality-control testing in the repository's master branch. After every commit to this branch, the tests will be executed on Travis CI in order to alert us should new (or newly updated) styles break any of the quality control rules.
If you are a style author, maintainer or would like to contribute to an existing style, you are advised to install the test environment on your computer in order to run the tests while you're working on a style and to make sure all tests are still passing before you commit any changes to the repository.
Before installing the test environment, please make sure that Ruby is available on you computer. If Ruby is not installed, please follow the official instructions on how to install it on your operating-system. The test environment should work on all current releases of Ruby and is backwards compatible with version 1.8.7. Some of our tests involve RelaxNG schema validation; these tests are based on libxml via Nokogiri. Please see these operating-system specific instructions if you have any problems installing the test setup because of these requirements.
Note: it seems in Ruby 1.8.7 you can get some failures with [] and {} comparison failing
Once Ruby is installed on your computer, it is easy to setup the test environment. First, clone into the official repository (if you have previously cloned the repository you can skip this step):
$ git clone https://github.com/citation-style-language/styles.git
$ cd styles
You should work directly on the master branch.
Next, we will install all requirements using Bundler (run [sudo] gem install bundler to make sure you have the latest version installed). Please note that depending on how Ruby is installed on your system you might need administrator privileges to install Ruby Gems, therefore, we have prefixed the commands with an optional [sudo]:
$ [sudo] bundle install
Once your bundle is installed there are two ways to run the tests. You can use rake:
$ rake
Or you can run the tests using rspec:
$ bundle exec rspec spec
The latter is useful if you would like to pass special parameters. For example, if your Terminal does not support colors, the output may be illegible. In this case try running the tests with:
$ bundle exec rspec spec --no-color
Or, if you would like a more verbose output of all tests, you can switch to a different format, for example:
$ bundle exec rspec spec --format documentation
Will print a summary of all tests for each style.
With the growing number of styles and tests available in the repository the number of test cases to execute has risen into the range of 100,000 – for obvious reasons, execution may take up to a few minutes on your computer. In order to allow for quicker feedback-loops when working on styles, you can set the environment variable CSL_TEST to control which styles to include in the test.
The CSL_TEST variable may contain a list of file names (separated by spaces) of styles to include; please note that the name should be the file's full base-name including the '.csl' extension, however, for additional flexibility, you can include regular expression wildcards as well.
$ CSL_TEST="apa.csl vancouver.csl" bundle exec rspec spec
$ CSL_TEST="chicago.*" bundle exec rspec spec
Finally, you can set the CSL_TEST variable to the special value 'git'; by doing that you can limit the styles to be included in the test run to those styles which are currently marked as modified in your local git repository.
$ CSL_TEST="git" bundle exec rspec spec
For colored output of the test results on Windows, see this guide.