Skip to content

Latest commit

 

History

History
114 lines (81 loc) · 4.56 KB

TESTING.md

File metadata and controls

114 lines (81 loc) · 4.56 KB
Raw

Testing Drupal Examples for Developers

The Drupal Examples for Developers project uses DrupalCI testing on drupal.org.

That means: It runs the testbot on every patch that is marked as 'Needs Review.'

Your patch might not get reviewed, and certainly won't get committed unless it passes the testbot.

The testbot runs a script that's in your Drupal installation called core/scripts/run-tests.sh. You can run run-tests.sh manually and approximate the testbot's behavior.

You can find information on how to run run-tests.sh locally here: https://www.drupal.org/node/645286

Examples is always targeted to the dev branch of Drupal core for the latest release. As of this writing, the latest release of Drupal core is 8.2.5, which means development for Examples should be against the Drupal 8.2.x development branch. When Drupal 8.3.0 is released, we'll start targeting Examples to 8.3.x, and so on.

You should at least run run-tests.sh locally against all the changes in your patch before uploading it.

Keep in mind that unless you know you're changing behavior that is being tested for, the tests are not at fault. :-)

Note also that, currently, using the phpunit tool under Drupal 8 will not find PHPUnit-based tests in submodules, such as phpunit_example. There is no suggested workaround for this, since there is no best practice to demonstrate as an example. There is, however, this issue in core: https://www.drupal.org/node/2499239

How To Run The Tests In The Drupal UI

Generally, you should run tests from the command line. This is generally easier than using Drupal's testing UI. However, here's how you can do it that way:

Enable the Testing module.

Visit the test list page at admin/config/development/testing.

Since the tests are organized by module, you can search for a module name and get all the tests for that module. For instance, type in 'node_type_example' for all the tests related to that module.

Click the check boxes next to the tests you want to run. If you find this tedious, it's time to learn to use the command line. :-)

Click 'Run Tests.' You're now running the tests.

Step-by-step: How To Run The Tests.

Begin with an installed Drupal codebase. Make a codebase, set up the database, etc. Note that you can use an existing Drupal instance but the best practice is to start fresh. Something not working right? Try a new installation.

Use the dev branch of core for the latest release of Drupal. As of this writing, it's 8.2.x. When Drupal 8.3.0 is released, we'll target 8.3.x.

Open the terminal window and move to the root directory of the Drupal installation:

$ cd path/to/drupal

Put Examples into the modules/ folder of the Drupal installation. If you are doing development on Examples, you should have already checked out the git repository into modules/, like this:

$ git clone --branch 8.x-1.x https://git.drupal.org/project/examples.git modules/examples

Now you can run run-tests.sh, which, despite having a .sh suffix is not a shell script. It's a PHP script.

You'll use the --directory option to have the test runner scan the Examples module directory for tests.

Also, importantly, if your test site has its own URL, you'll need to supply that with the --url option. For instance, under MAMP, you must specify --url http://localhost:8888/.

You can also use --concurrency to speed up the test run, and --browser to see detailed test results in a web browser instead of just text output in the terminal.

$ php ./core/scripts/run-tests.sh --browser --concurrency 10 --url http://localhost:8888/ --directory modules/examples

This should run all the tests present in Examples. If you add a test and it doesn't appear in the list of tests to run, then you'll need to double-check that it's in the proper test namespace and that the class name (and thus the file name) ends in Test.

What Tests Should An Example Module Have?

Examples has a checklist for each module: https://www.drupal.org/node/2209627

The reason we care about these tests is that we want the documentation of these APIs to be correct. If Core changes APIs, we want our tests to fail so that we know our documentation is incorrect.

Our list of required tests includes:

  • Functional tests which verifies a 200 result for each route/path defined by the module.
  • Functional tests of permission-based restrictions.
  • Functional tests which submit forms and verify that they behave as expected.
  • Unit tests of unit-testable code.
  • Other. More. Better.