How to test Decidim engines

RSpec

Requirements

You need to create a dummy application to run your tests. Run the following command in the decidim root’s folder:

bundle exec rake test_app

Running a specific test file or just a single spec

If you are writing new specs, you can run the tests contained in a single file by opening a console window in the corresponding module and calling rspecon the file. For example:

cd decidim-participatory_processes
bundle exec rspec spec/forms/participatory_process_form_spec.rb

You can also run a single test by appending its start line number to the command:

bundle exec rspec spec/forms/participatory_process_form_spec.rb:134

We also have a helper at bin/rspec that you can use to run a single spec from the command line:

bin/rspec decidim-participatory_processes/spec/forms/participatory_process_form_spec.rb

Running tests for a specific component

A Decidim engine can be tested running the rake task named after it. For example, to test the proposals engine, you can run:

bundle exec rake test_proposals

Running the whole test suite

You can also run the full thing including test application generation and tests for all components by running

bundle exec rake test_all

But beware, it takes a long time…​ :)

Running specs in parallel

We have configured the parallel_tests gem. For using it, you will need to follow these steps:

  1. Configure the TEST_ENV_NUMBER environment variable with the number of processes that you want to run in parallel.

  2. Run the commands to prepare the test database

cd spec/decidim_dummy_app/
bundle exec rake parallel:create
bundle exec rake parallel:prepare
cd -

From now on you can use the bundle exec rake parallel:spec task, for instance for running all the system specs from any module:

cd decidim-participatory_processes
bundle exec rake parallel:spec[spec/system/]

This same commmand without the parallelization (cd decidim-participatory_processes && bundle exec rspec spec/system/) took 26 minutes 21 seconds. With parallel_specs, this runs in 10 minutes 27 seconds.

These numbers are depend on your machine, the configuration was:
* TEST_ENV_NUMBER=4
* Intel(R) Core(TM) i5-6500T CPU @ 2.50GHz

Jest

We use Jest for testing our Javascript code.

Running a specific test file

npx jest decidim-core/app/packs/src/decidim/external_link.test.js

Running the whole test suite

npm run test

Continuous integration

The tests are also run when a new commit is added to the develop or releases branches, or added to a Pull Request. In the latter case, only the tests for the modules affected by any the PR commits will be executed.

This means that the workflows defined for each module in the folder .github/workflows/ should be always updated with the module’s dependencies list. The script .github/workflows/dependencies.sh can be helpful to keep those files updated until we have an automatic process to do it.

You can read more about the continuous integration configuration at GitHub.