Environment basics

How Moodle sees Behat

Moodle uses a custom Behat extension that does a lot of the hard work. It's part of a plugin from Composer, a PHP dependency manager. This plugin takes care of loading all the required testing steps and Behat helper libraries included in the Moodle Behat extension. Generally, all you really need to provide is the behat.yml file that contains configuration data and tells Behat where to find your tests and custom steps, but Moodle can do this for you (mostly) automatically with some scripts.

Moodle looks for Behat tests in a pre-defined folder structure. When you are in a testing environment context you will need to run some scripts to tell Moodle when it needs to revisit that folder structure to find new test files. These scripts basically build the behat.yml file.

default:
  paths:
    features: /Users/alfonso/Sites/moodle/lib/behat/features
    bootstrap: /Users/alfonso/Sites/moodle/lib/behat/features/bootstrap
  context:
    class: behat_init_context
  extensions:
    Behat\MinkExtension\Extension:
      base_url: 'http://localhost:8888/moodle'
      goutte: null
      selenium2: null
    Moodle\BehatExtension\Extension:
      formatters:
        moodle_progress: Moodle\BehatExtension\Formatter\MoodleProgressFormatter
      features:
        - /Users/alfonso/Sites/moodle/blocks/activity_modules/tests/behat
        - /Users/alfonso/Sites/moodle/blocks/comments/tests/behat
      steps_definitions:
        behat_block_comments: /Users/alfonso/Sites/moodle/blocks/comments/tests/behat/behat_block_comments.php
        behat_course_download: /Users/alfonso/Sites/moodle/blocks/ucla_course_download/tests/behat/behat_course_download.php
        behat_ucla_course_menu: /Users/alfonso/Sites/moodle/blocks/ucla_course_menu/tests/behat/behat_ucla_course_menu.php
  formatter:
    name: pretty
    parameters:
      decorated: true
      verbose: true

Behat init

The primary script that sets up Behat in Moodle is found in admin\tool\behat\cli\init.php. When you run this, a few things can happen.

1. If it is the first time you use your environment (or you've introduced new code), Moodle will launch a setup script that basically clones your database tables with a different prefix. Don't worry about the specifics of this, just know that it may take a while.

2. Moodle will upgrade its behat plugin via Composer.

3. Moodle will generate the behat.yml file that tells the Moodle Behat plugin where to find all the tests.

Caveats

A common problem that occurs here is that you will forget to update your git submodules when you run the init.php script. ALWAYS run git submodule init && git submodule update to update your submodules. Failure to do so will likely result in your database becoming corrupt. You have been warned!

Behat util

This is another script found in admin\tool\behat\cli\util.php that is used as a switch with two flags: --enable and --disable. Since we usually reserve a separate Moodle instance specifically for testing, we don't necessarily need to disable our environment. When you toggle the switch, however, it will result in the rebuild of the behat.yml file. When you run the --enable flag, you implicitly run the init.php script.

After you run the init or enable scripts, Behat will print out the command you need to run to run all Behat tests. It usually looks like so:

vendor/bin/behat --config /Users/alfonso/Sites/moodledata/behat/behat/behat.yml

You basically paste that into your console and run it. It will run all Behat tests in Moodle. This may not be what you want, you usually want to run the test you just created. To do so, add the --tags flag. We use tags to identify tests.

vendor/bin/behat --config /Users/alfonso/Sites/moodledata/behat/behat/behat.yml --tags @block_ucla_course_download

If you want to get more descriptive feedback from the console about what step is running, you can set the --format flag.

vendor/bin/behat --config /Users/alfonso/Sites/moodledata/behat/behat/behat.yml --tags @my_feature_test --format pretty 

This will print more info to you console; the currently running steps and associated PHP functions in the console, as well as the exact place where your test fails.

Feature files

Behat uses the .feature extension to identify tests. These files can be found inside the tests directory inside moodle plugins. This is where you will also find unit tests and other relevant testing assets. Moodle looks for Behat tests specifically in the test\behat folder. So you will usually have:

blocks\ucla_course_download\tests\behat
local\ucla\tests\behat

And so forth. You can find these all over moodle with grep:

$ git grep Feature:
admin/tests/behat/display_short_names.feature:Feature: Display extended course names
admin/tests/behat/filter_users.feature:Feature: An administrator can filter user account
admin/tests/behat/upload_users.feature:Feature: Upload users
...

Behat PHP files

Sometimes you will need to write unique steps for the plugin you are testing. These steps are written in PHP files with the usual PHP OOP constructs. These files are also included in the test\behat folder withe a filename prefix of behat_*.php.

The Yaml file

You should never have to manually edit the Yaml file. The Moodle Behat scripts generate this file for you by scanning the folder structure, searching for *.feature and behat_*.php files and generating the correct paths for your tests. If you find yourself editing this file, it means your testing environment is incorrectly set up.