Running tests

Set up the test environment and run Redmine’s test suite, including unit, functional, integration, and system tests.

Redmine uses the Rails built-in testing stack (Minitest). Tests live under the test/ directory and are organised by type.

test/
├── controllers/        # Controller tests
├── functional/         # Legacy functional tests
├── helpers/            # View helper tests
├── integration/        # Integration tests
├── mailers/            # Mailer tests
├── models/             # Model/unit tests
├── system/             # Capybara system tests
├── unit/               # Additional unit tests
├── fixtures/           # Test data (YAML)
└── test_helper.rb

Prerequisites

Before running tests you need:

1. A configured development database and a separate test database (see your config/database.yml)
2. All gem dependencies installed, including the test group

If you previously ran bundle install while skipping test dependencies, delete .bundle/config and run bundle install again to pick up the test gems.

rm -f .bundle/config
bundle install

Key test gems installed by this step:

Gem	Purpose
rails-dom-testing	DOM assertions in controller tests
capybara	Browser-based system tests
rubocop	Static analysis (see Contributing)
rubocop-performance	Performance cops
rubocop-rails	Rails cops

Setting up the test database

Create and migrate the test database before the first run:

bundle exec rake db:create RAILS_ENV=test
bundle exec rake db:migrate RAILS_ENV=test

Redmine uses fixture files (YAML) in test/fixtures/ to seed test data. Rails loads them automatically when you run the test suite.

Running the full test suite

bundle exec rake test

This runs all unit, functional, and integration tests. It excludes Capybara system tests and the Redmine.pm Apache module tests.

Run tests in parallel

Speed up the suite by setting PARALLEL_WORKERS to the number of parallel processes you want:

PARALLEL_WORKERS=8 bundle exec rake test

List available test tasks

rake --tasks test

Running specific tests

Single test file

ruby test/unit/issue_test.rb

System tests (Capybara)

System tests drive a real browser via Capybara and require Chrome to be installed and available on your PATH. Redmine uses selenium-webdriver (>= 4.11.0) to communicate with ChromeDriver. You need to have ChromeDriver installed and available on your PATH as well.

rails test:system

Environment variables for system tests

Variable	Description
CAPYBARA_SERVER_HOST	IP address the test server listens on (e.g. 0.0.0.0 for all interfaces)
CAPYBARA_SERVER_PORT	Port for the Capybara test server
CAPYBARA_APP_HOST	Custom application URL (default: localhost)
SELENIUM_REMOTE_URL	Remote Selenium/ChromeDriver URL
GOOGLE_CHROME_OPTS_ARGS	Comma-delimited Chrome options

Run system tests in headless mode

export GOOGLE_CHROME_OPTS_ARGS="headless,disable-gpu,no-sandbox,disable-dev-shm-usage"
rails test:system

Run against a remote Selenium instance (e.g. Docker)

export SELENIUM_REMOTE_URL="http://selenium-host:4444/wd/hub"
export CAPYBARA_SERVER_HOST="0.0.0.0"
rails test:system

SCM (version control) tests

Redmine supports multiple version control systems. Integration tests for each require a local test repository.

# List available SCM test setup tasks
rake --tasks test:scm:setup

# Set up all test repositories at once
rake test:scm:setup:all

Repositories are unpacked into {redmine_root}/tmp/test. If a test repository is not present, the tests that require it are automatically skipped.

LDAP tests

To run the LDAP authentication tests:

1. Start a test LDAP server

   Load the bundled LDAP export into your test LDAP server:

   # Import the test data
   ldapadd -x -D "cn=admin,dc=redmine,dc=org" -w secret \
     -f test/fixtures/ldap/test-ldap.ldif
   

   The tests expect the server at 127.0.0.1:389 by default.

2. Override the host if needed

   If your LDAP server runs on a different host, set:

   export REDMINE_TEST_LDAP_SERVER=your-ldap-host
   
3. Run the tests

   bundle exec rake test
   

   If the LDAP server is unreachable, LDAP-dependent tests are skipped automatically.

Redmine.pm tests

The Redmine.pm tests are a work in progress and require a non-trivial server setup.

These tests exercise the Apache mod_perl integration for repository access control. You need:

• Apache with mod_perl and mod_dav_svn
• Redmine.pm configured
• An empty SVN repository accessible at http://127.0.0.1/svn/ecookbook

Run the tests with:

ruby test/extra/redmine_pm/repository_subversion_test.rb

Set REDMINE_TEST_DAV_SERVER if your SVN server is not on localhost:

export REDMINE_TEST_DAV_SERVER=your-svn-host
ruby test/extra/redmine_pm/repository_subversion_test.rb

Static analysis

RuboCop

RuboCop checks Ruby code against the project style rules. Run it before submitting a patch:

# Check all files
bundle exec rubocop

# Check specific files
bundle exec rubocop app/models/issue.rb

See Contributing for details on the project’s RuboCop configuration.

Stylelint (CSS)

# Install Node dependencies (first time only)
yarn install

# Lint CSS files
npx stylelint "app/assets/stylesheets/**/*.css"

Troubleshooting

Tests fail with 'database does not exist'

Create the test database and run migrations:

bundle exec rake db:create RAILS_ENV=test
bundle exec rake db:migrate RAILS_ENV=test

Missing test gems (LoadError)

Delete your bundle config and reinstall with all groups:

rm -f .bundle/config
bundle install

Capybara tests fail: Chrome not found

Install Google Chrome and make sure google-chrome or google-chrome-stable is on your PATH. Also install ChromeDriver matching your Chrome version and ensure it is on your PATH. Redmine uses selenium-webdriver to communicate with ChromeDriver.

SCM tests are skipped

Test repositories have not been set up. Run:

rake test:scm:setup:all

Repositories will be extracted to tmp/test/.

LDAP tests are skipped

The LDAP server is not running or not reachable at 127.0.0.1:389. Start your test LDAP server and ensure it is accessible, or set REDMINE_TEST_LDAP_SERVER to point to the correct host.