Overview
Backdrop core and many contrib modules include tests that can be run manually or (in the case of core modules) automatically. The automatic tests are useful to help detect when changes in a module causes problems in functionality due to unexpected side effects or errors in coding. In the case of core modules, all tests are run on several different versions of PHP, to help ensure that the module remains compatible with all supported versions of PHP.
The test suite for a module is typically stored in a module subdirectory tests, which contains files that define the tests themselves, plus any supporting modules that are used solely for testing.
Writing tests
A good place to start when writing tests (or modifying/debugging existing ones) is to examine an existing test to see what is typically done. Backdrop contains a collection of well documented API examples, located at https://backdropcms.org/project/examples, which include Example: Simpletest, a module that creates a new node type called "SimpleTest Example Node Type," and then tests for it.
Another good place to look is inside any of the core modules, most of which also contain their own test suite.
The simplest form of a test suite is illustrated by the core Contact module, whose directory structure looks like this:
contact/
config/
...
tests/
contact.test
contact.tests.info
views/
...
...
A Backdrop test suite should at minimum contain two files: modulename.test, which contains the classes for testing and test code, and modulename.tests.info, which declares the test classes and where they should be grouped (and where they are found in the UI testing, see below).
Each test class (the name in [...] in the .tests.info file) is a subclass of class BackdropWebTestCase. This class typically contains a setUp() method, which sets up the testing scenario, and one or more methods of the form testSomething(), each of which tests one or more aspects of the module's functionality by various combinations of loading pages, filling out forms, taking actions, and then performing assertions based on the expected results.
Many test suites also contain "helper modules", which are only used in testing. These modules' files should be stored within the tests directory, and by convention, have names ending in _test. Thus, for example, a module modulename containing tests and a helper module modulename_test would have a directory structure like this:
modulename/
modulename.info <-- the info file for the module
modulename.module <-- the module's file
tests/
modulename.tests.info <-- declaration of the test classes
modulename.test <-- implementation of the test classes
modulename_test.info <-- info file for a helper module to assist in testing
modulename_test.module <-- the helper module's file
...
...
To help distinguish between the test class declaration file and the helper module's .info file (whose names may be very similar), you may wish to put the helper module's files into their own subfolder, like this:
modulename/
modulename.info <-- the info file for the module
modulename.module <-- the module's file
tests/
modulename.tests.info <-- declaration of the test classes
modulename.test <-- implementation of the test classes
modulename_test/
modulename_test.info <-- info file for a helper module to assist in testing
modulename_test.module <-- the helper module's file
...
...
Testing helper modules should have hidden = TRUE set in their .info file so that they do not show up in the module list page in the user interface.
There are many methods provided by BackdropWebTestCase to assist in carrying out the tests. A detailed discussion is beyond the scope of this documentation page (at least, at present), but because Backdrop's testing framework is based on Drupal 7's framework, the Drupal 7 Automated Testing documentation is a useful guide. You can also just look through the various tests for core modules to see examples of how various types of testing are carried out.
Testing and JavaScript
Backdrop makes extensive use of JavaScript, creating, for example, pop-up dialogs in many places rather than loading new web pages. The test suite simulates an environment in which JavaScript is disabled, though, so if you are working through a series of actions in the UI that will be emulated in a test function, you should disable Javascript to ensure that the actions you are experiencing are those that the testing function will be emulating.
Porting tests from Drupal 7
Backdrop's testing framework is very close to Drupal 7's, but there is one significant difference. In Drupal 7, you only needed to create modulename.test containing the test classes. In Backdrop, you must create also the modulename.tests.info that declares the test classes.
The Coder Upgrade module is a useful tool to assist in porting a Drupal 7 module to Backdrop CMS. It will also do some of the work in porting the tests, but you should carefully check for the existence and contents of both modulename.test and modulename.tests.info.
You should also check the tests themselves, typically by running them from the user interface (see below). It is not uncommon for tests that passed in Drupal 7 to fail (at least, initially) in Backdrop due to changes in Backdrop core (for example, moving database variables to Configuration Management). In many cases, though, small changes in the tests will get them running successfully again.
Running tests
Running tests through the User Interface
Tests may be run through the user interface after enabling the Testing module (whose machine name, i.e., the module folder name, is simpletest). Visit /admin/config/development/testing to select the tests to run.
When making a contribution to a module, it is a good idea to run the module's tests from the UI before submitting your pull request, to help ensure than your change didn't inadvertantly break any tests.
Running tests through the Command Line
Backdrop core includes a shell script under /core/scripts/run-tests.sh. This can be run from the command line such as:
# Run a single test class:
./core/scripts/run-tests.sh --url http://backdrop.dev --color --force --verbose BlockTestCase
# Run the entire test suite:
./core/scripts/run-tests.sh --url http://backdrop.dev --color --force --verbose --allThis script takes a variety of useful flags. Documentation may be found in the run-tests.sh documentation.
Running tests automatically on pull requests
Pull requests again Backdrop core will automatically be tested using the GitHub Actions service. This service runs the run-tests.sh script (on multiple PHP versions) and posts the result to the pull request.