Behat

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Behat is a Behaviour Driven Development (BDD) framework, allows development and testing guided by steps to simulate users interaction.

Support for multiple browsers drivers (including selenium 2) http://mink.behat.org/#different-browsers-drivers
Extension to connect to Jira (linking issues to features)

This document is a work in progress (STABLE team week off project) and at the moment it should not be taken into account for nothing out of this scope nor nothing official.

Example

The expected behaviours are specified as scenarios.

Basic scenarios

 Scenario: Login as an existing user
   Given I am on "login/index.php"
   When I fill in "username" with "admin"
   And I fill in "password" with "moodle"
   And I press "loginbtn"
   Then I should see "Moodle 101: Course Name"

 Scenario: Login as an unexisting user
   Given I am on "login/index.php"
   When I fill in "username" with "adminasdasd"
   And I fill in "password" with "moodlesdfasdf"
   And I press "loginbtn"
   Then I should see "Invalid login, please try again"

Complex scenario

The aim of this project is to be able to define scenarios like this. Note the quoted strings are received as variables by the steps definitions which will process them.

 Scenario: A teacher adds a discussion
   Given I am logged as a "teacher"
   And I go to a course
   And I create a "forum" activity
   And I view the "forum" activity    # The step definition class will keep a reference to the lasts steps
   When I add a "forum_discussion" filling the fields "subject,message[text]" with "I'm the user subject,Dealing with \, split"    #     Wrapper step, it will redirect the petition to a "forum_discussion" method
   Then I should see "Discussion"
   And I should see "Subject"
   And I should see "I'm the user subject"

In order to be able to process the "logged as a $roleshortname" or the "a course" statements the /behat.yml file should be filled with your own installation data

Input Tables

To improve readability and reduce unnecessary verbosity; complex scenarios can use input tables to group similar types of input:

 Scenario: Add Offline text assignment
   Given that I add "assignment" to section "1"
   And I fill in the form:
     | field_name       | value  |
     | Assignment name  | Test3  |
     | Description      | Test3  |
     | Online text      | No     |
     | File submissions | No     |
   And I click "Save and display"
   Then the title "Test3" should be displayed

or even:

 Scenario: Set Submissions from date
   Given that I add "assignment" to section "1"
   And I fill in the form:
     | field_name             | value |
     | Assignment name        | Test4 |
     | Description            | Test4 |
   And I enter the dates in "Allow submissions from":
     | date_unit | value     |
     | day       | 1         |
     | month     | September |
     | year      | 2012      |
     | hour      | 09        |
     | minute    | 05        |
   And I click "Save and display"
   Then the title "Test4" should be displayed

Background Steps

In a feature where certain steps are repeated in every scenario, a feature background can be defined. The feature background will be repeated just before every scenario in the feature:

 Background:   
   Given I am logged in as a "teacher"
   And I go to a course

This also helps to increase readability and reduce the verbosity of the tests.

Teardown

Most automated tests require teardown steps after each test has run. The teardown ends the test session, closes browsers etc. Behat does this automatically after every scenario, so you don't have to worry about adding any teardown steps.

Packages

There are two packages, one with the features files (scenarios like the above examples) and a package with Moodle contexts and steps definitions (PHP code to interact with selenium2). Only the features project is required since it manages all it's dependencies, including the Moodle contexts

Requirements

PHP 5.3.3
PHPUnit
There are other packages and PHP settings requirements, but they be checked by the composer installer

Installation

Clone the Moodle features project: https://github.com/moodlehq/moodle-behat-features
Follow the README instructions

Usage

To test a feature type "bin/behat features/FEATURENAME.feature" from the clone directory
If you want to execute the feature in a Selenium Grid2 you can specify another behat profile: "bin/behat --profile seleniumGrid2Firefox features/FEATURENAME.feature"

Update to latest versions

Behat uses the composer dependencies management system, all the project dependencies can be updated with two commands.

cd to behat directory
./composer.phar self-update
php composer.phar update

Development environment

One of 'moodle-behat-features' dependencies is 'moodle-behat-contexts', which is a work in progress, to set up the development environment to work/commit to both projects with the composer dependency management system advantages, after installing the moodle-behat-features according to it's README file, you can git clone the moodle-behat-contexts project into vendor/moodlehq/behat-contexts and name your remote as 'composer' when you update your packages composer reads this remote name and updates the 'moodle-behat-contexts' package from the remote repository you specified.

Steps

Every step is processed in a step definition, which is defined in "context" classes. The Behat project has a main context class, FeaturesContext, but it allows more contexts to be added as subcontexts, Moodle is one of this subcontexts, all the Moodle steps definitions are split in a modular way following the [Frankenstyle] format, and are loaded dynamically by Moodle\Behat\Context\MoodleContext.

A quick view of the hierarchy:

FeaturesContext
- Sanpi/Behatch/Context
  - Behat extension with a lot of common actions like send REST petitions, store screenshots, DOM / XPath parsing
- Moodle/Behat/Context
  - MoodleContext as a reference to the rest of the Moodle components
  - BaseContext abstract class with helper methods
    - CoreContext
      - contains basic steps definitions like visit($url), pressButton($button) to manage the browser
      - The cross-component and the most common Moodle actions like iAmLoggedAsA($roleshortname) or aUserAssignedInContextOfContextlevel($roleshortname, $instanceid, $contextlevel) to speed up the creation of scenarios
    - CourseContext
      - Course related steps definitions
    - ModForumContext
      - mod_forum related steps definitions
    - ...

In a future with a lot of Moodle components, having a single shared directory could not be the best way to store the contexts, other directory hierarchies more similar to a moodle distribution can be made without changing references between components since they are currently made using the Frankenstyle component name.

Links

Moodle features project

Moodle contexts repository

Documentation