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 rspec
on 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’ve configured the parallel_tests gem. For using it, you’ll need to follow these steps:
-
Configure the TEST_ENV_NUMBER environment variable with the number of processes that you want to run in parallel.
-
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
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.