ArchivesSpace End-to-End Test Suite

For more context on the End-to-End test suite and how to contribute tests, see our wiki-page.

Recommended setup

Using a version manager

The required Ruby version for the e2e test application is documented in [./.ruby-version](./.ruby-version).

It is strongly recommended to use a version manager (such as mise) to be able to switch to any version that a given project requires.

mise

We recommend using mise to manage Ruby (and other runtimes). Installation instructions are available at Getting started.

Alternatives to mise

If you wish to use a different Ruby manager or installation method, see Ruby’s installation documentation.

Installation

From the ArchivesSpace root directory, navigate to the e2e test application, then install Ruby, Bundler, and the application dependencies:

# 1. Navigate to e2e-tests directory
cd e2e-tests

# 2. Install Ruby at the version specified in ./.tool-versions
mise install

# 3. Install the Bundler dependency manager
gem install bundler

# 4. Install project dependencies
bundle install

Running the tests locally

Just working on the e2e tests with Docker

If you are just working on e2e tests and not touching the ArchivesSpace application, you can run e2e tests locally against the latest ArchivesSpace master branch build using Docker.

Install Docker Desktop

Docker Desktop is a one-click-install application for Linux, Mac, and Windows. It provides both terminal and GUI access to Docker. Download and install the appropriate version for your operating system from the link above. You can also use alternative software for running Docker containers, such as OrbStack for macOS.

Run the latest ArchivesSpace Docker image

# Get the latest ArchivesSpace `master` branch build
docker compose pull

# Start ArchivesSpace servers
docker compose up

Verify the servers are running by opening http://localhost:8080 in a browser.

Working with an ArchivesSpace development environment

You can run the e2e test suite against your local ArchivesSpace development environment. But be aware that your database, Solr index, and any configuration changes will need to be reset.

Reset your database and Solr index

Make sure your ArchivesSpace instance has a blank database and blank solr index.

Restore default configuration options (except for AppConfig[:db_url])

Make sure you override any local changes to the default configuration options (via ../common/config/config.rb) by commenting them out or deleting them, except for AppConfig[:db_url] (which is required for using the MySQL database).

Run the frontend dev server

Start the frontend:devserver as described here. Verify it is running by opening http://localhost:3000/ in your browser.

Run the public dev server

Start the public:devserver as described here. Verify it is running by opening http://localhost:3001/ in your browser.

Set the STAFF_URL environment variable

Set your STAFF_URL environment variable to point the e2e tests at the local development server:

export STAFF_URL='http://localhost:3000'

Set the PUBLIC_URL environment variable

Set your PUBLIC_URL environment variable to point the e2e tests at the local public interface:

export PUBLIC_URL='http://localhost:3001'

Running tests

After setting the appropriate STAFF_URL and PUBLIC_URL environment variables as described above, run the desired test(s) according to the following commands.

All test files at once

bundle exec cucumber staff_features/

All scenarios in a specific file

bundle exec cucumber staff_features/assessments/assessment_create.feature

A specific scenario in a specific file

bundle exec cucumber staff_features/assessments/assessment_create.feature --name 'Assessment is created'

Debugging

Add a byebug statement in any .rb file to set a breakpoint and start a debugging session in the console while running. See more here. Don’t forget to remove any byebug statements before a git push…

If you need to see the browser while running the test scenario and debugging, add a HEADLESS='' argument, as in:

bundle exec cucumber HEADLESS='' staff_features/

Linters

This test suite uses two linters, cuke_linter and rubocop, to maintain code quality.

# Lints Cucumber .feature files
bundle exec cuke_linter

# Lints Ruby .rb files
bundle exec rubocop

Editor integration (optional)

ArchivesSpace provides optional VS Code workspace tasks that can run the end-to-end test suite without manually setting environment variables or changing directories.

These tasks execute the same cucumber commands described above and are simply a convenience wrapper around the documented command-line workflow.

Setup instructions are documented in the VS Code guide here.

Contributors not using VS Code can ignore this section and run the tests directly from the command line.