decidim/decidim

= 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:

[source,bash]
----
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:

[source,bash]
----
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:

[source,bash]
----
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:

[source,bash]
----
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:

[source,bash]
----
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

[source,bash]
----
bundle exec rake test_all
----

But beware, it takes a long time... :)

=== Running specs in parallel

We have configured the https://github.com/grosser/parallel_tests[parallel_tests gem]. For
using it, you will 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

[source,bash]
----
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:

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

This same command 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.

[NOTE]
-----
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

[source,bash]
----
npx jest decidim-core/app/packs/src/decidim/external_link.test.js
----

=== Running the whole test suite

[source,bash]
----
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 https://github.com/decidim/decidim/blob/develop/.github/workflows/README.md[GitHub].