Writing acceptance tests

Jump to: navigation, search

Introduction

This documentation gives some hints, how to write behat tests for core and for plugins. The focus of the documentation is on behat tests for plugins. They are written in some kind of natural language and describe how the front-end of moodle should behave, when a user interacts with it. Each test consists of a set of so called steps in a GIVEN, WHEN, THEN style:

  • GIVEN: These steps outline the state of your moodle platform at the start of your test. Here you can create users, courses and plugin instances.
  • WHEN: These steps usually execute the functionality of your plugin, which is under test.
  • THEN: These steps describe the expected behaviour of your plugin. They usually check if different elements can or can't be seen.

To initialize and run your tests, please follow the instructions of Running_acceptance_test.

Create you own tests

Behat tests are located within the directory tests/behat of your plugin. The different tests are defined in files with the ending *.feature. First, you have to define the header of your test:

@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.

The tags on top of the feature description can be used to select specific test cases when running the tests. The '@javascript' tag should only be used, if javascript is needed to execute your test. This is dependent on the step you will use in your definition. Javascript tests are usually much slower than tests executed without javascript.

Afterwards you can specify a scenario:

@javascript
  Scenario: Description of your scenario, which you want to test.
    When I log in as "student1"
    And I am on "Course 1" course homepage

Again you can define specific tags. Afterwards you write the steps, which should be executed during your test.

Multiple Scenarios

You can have an arbitrary amount of scenarios within a test. Please make sure they all belong to the same feature. If you have certain steps, which should be executed for every scenario of a feature, you can define them using a background:

Background:
    Given the following "courses" exist:
      | fullname | shortname | category | groupmode |
      | Course 1 | C1        | 0        | 1         |
    And the following "users" exist:
      | username | firstname | lastname | email |
      | teacher1 | Theo | Teacher | teacher1@example.com |

This is usually used, to define the different GIVEN steps.

Use existing steps

There are different ways how to effectively browse the available existing steps:

Moodle Administration

Moodle offers within its administration menu under Site Administration > Development > Acceptance Testing a complete and searchable list of all available step definitions. However, make sure you installed the behat test site first!

PhpStorm

In PhpStorm or IntelliJ you can install the behat extension. Then you get auto completions within feature files, which helps a lot during behat test development.

Advanced use cases

Most of the time the usage of existing step definitions is straight forward. However, there are some exceptions were it might get complicated. Some of them are listed here:

Field groups

This section describes how you can use the step definitions

When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"

for field groups. Examples for such field groups are the duration field or the date_time_selector. These are not displayed as one single input field within the front-end but consist of multiple input fields within one row. You can access each single input field of a group using

identifierOfYourField[keyOfTheSpecificInput]

Examples would be:

When I set the following fields to these values:
  | myDate[day]             |   21   |
  | myDate[month]           |   12   |
  | myDate[hour]            |   14   |
  | myDuration[number]      |   10   |
  | myDuration[unit]        | days   |
Relative dates

When testing plugins with deadlines, for instance for submissions, it is often necessary to set certain time values to dates relative to today. You can specify a relative time enclosed within two ## blocks. For example:

  • ## yesterday ##
  • ## 2 days ago ##

You can use everything according to [1].

Especially useful are the relative formats from: [2]

Additionally, you can specify a format you want the date to be returned into:

  • ## yesterday ## myformat ##

These formats can be used as outlined in [3]. This can be combined with the field groups:

When I set the following fields to these values:
  | myDate[day]             |   ## yesterday ## j ##   |
  | myDate[month]           |   ## yesterday ## n ##   |
  | myDate[year]            |   ## yesterday ## Y ##   |