Testing and Developing Blacklight

Pre-requisites

• Ruby
• Docker
• Docker Compose

Getting started

If you want to start off clean, make sure you have removed artifacts from prior runs, such as Gemfile.lock and the .internal_test_app/ directory.

$ rm -rf Gemfile.lock .internal_test_app/

Also, you may also want to pull the latest Blacklight commits.

$ git pull origin main

Update the Solr docker containers. This will provide you the latest Solr image as specified by SOLR_VERSION in the .env file, which you are free to customize for your needs.

$ docker-compose pull 

Decide what versions of Ruby and Rails you will test with locally. Make sure the RAILS_VERSION environment variable is set appropriately. (To see what versions are already being tested with Blacklight, check out .github/workflows/ruby.yml.)

$ export RAILS_VERSION=7.0.3.1

And then install gem dependencies.

$ bundle install

Finally you can run the default rake task. (Prefix with bundle exec if that's how you Ruby.)

$ rake

This task does the following:

1. Validates that the Blacklight codebase satisfies Rubocop
2. Spins up Solr via docker-compose
3. Builds a test application (with the version of Rails specified in RAILS_VERSION)
4. Indexes seed data in the test application and Solr
5. Runs the Blacklight test suite

Step by step, with more control

The default rake task will re-index test data in solr and re-build the test application (if needed). Running the full test suite can be time-consuming. You may prefer to set up the environment and run tests as separate steps.

To spin up Solr in the background:

$ docker-compose up -d solr

To create the dummy test app (in the .internal_test_app directory):

$ rake engine_cart:generate

To index the test data, from inside the .internal_test_app directory run the following. (Prefix rake with bundle exec if that's how you Ruby.)

$ RAILS_ENV=test rake blacklight:index:seed

Then back in the blacklight directory, run all the specs. (Prefix with bundle exec if that's how you Ruby.)

$ rspec

Or run just one spec. (Prefix with bundle exec if that's how you Ruby.)

$ rspec just/one_spec.rb