Writing your first test

Walking you through your first test

Writing a Behat test has a cookbook approach. This will walk you with the assumption that your environment is already working, and you need to add a test to a branch you are working on.

Your feature

Let's suppose you need to test that a student can reach their user profile from the control panel. This tests requires you to log into a course as student, find the control panel, and then find the link to edit the student's user profile. We'll make an edit, then verify it. So we can break it down to the following steps:

• log in as a student
• navigate to a course
• find the control panel
• find the link to edit the user profile
• make an edit
• verify

Creating your files

Since this tests some of the functionality of the Control Panel, we should add our feature file in there.

blocks/ucla_control_panel/tests/behat

A good name for this feature could be user_profile.feature, so let's create the file:

blocks/ucla_control_panel/tests/behat/user_profile.feature

Writing your feature

To start, tag your feature file with @ucla and @block_ucla_control_panel. We use the @ucla for all our tests. The other tag tells us what plugin you are testing. Next you'll need to describe your feature. We use the 'user story' format for this.

Starting the feature

@ucla @block_ucla_control_panel
Feature: Control Panel user profile
  In order to edit my profile
  As an student
  I need to access the User Profile page through the control panel

This bit of code does not get executed. It's meant to be human readable. To start the executble

Generating data

Remember that each test gets clean slate, so you need to set up the environment for your Feature. In this case, we need a course and a student enrolled in that course. This breaks down as:

• course
• student
• student enrolled in that course

Moodle gives us steps to do all this out of the box. With the following you can generate the user, the course, and the enrollment.

    Given I am in a ucla environment
    And the following "users" exists:
      | username | firstname | lastname | email |
      | student1 | Student | 1 | student@asd.com |
    And the following "courses" exists:
      | fullname | shortname | format |
      | Course 1 | C1 | ucla |
    And the following "course enrolments" exists:
      | user | course | role |
      | student1 | C1 | student |

This the minimum amount of setup to get you started with the testing scenario.

Acting like a user

To execute the test, you need to pretend you're the user. As a student, you want to log in, go to the course you're enrolled in, then visit the control panel and click on the 'Edit user profile' link. As an itemized list this can look like:

• Log in
• Follow course link
• Press control panel button
• Follow the 'Edit user profile' link
• Verify information

Given I log in as ucla "student1"
And I follow "Course 1"
And I press "Control Panel"
When I follow "Edit user profile"
Then I should see "First name"

Creating a Scenario

Behat requires you to describe your testing steps in a Scenario. A single test can contain several scenarios, this way you can partition a test into smaller chunks. For this starting test, we're only doing a single scenario, so we'll describe it as:

Scenario: Editing user profile as student
    Given I am in a ucla environment
    And the following "users" exists:
      | username | firstname | lastname | email |
      | student1 | Student | 1 | student@asd.com |
    And the following "courses" exists:
      | fullname | shortname | format |
      | Course 1 | C1 | ucla |
    And the following "course enrolments" exists:
      | user | course | role |
      | student1 | C1 | student |
    # Environment is set up, begin testing steps
    Given I log in as ucla "student1"
    And I follow "Course 1"
    And I press "Control Panel"
    When I follow "Edit user profile"
    Then I should see "First name"

The scenario encapsulates a single test. If you were to add a separate scenario, you would need to generate the suitable environment state. For example, another test might require you to have an instructor and two more students. You would need to generate that data in the new scenario.

Running your test

So the hard part is done, now we need to run the actual test! This is primarily done through the console with a combination of enabling the Behat environment in Moodle and running your Selenium server.

Selenium standalone server

We treat this as a black box. You just need to have the Java JAR file, and run it whenever you need to run Behat. The usual command is

java -jar selenium-server-standalone-2.41.0.jar

Your version of the server may vary.

Moodle init

Since you added this test, you need to tell Moodle to rebuild the behat.yml file so that Behat can see it. You do this by running the init script.

If your feature happens to trigger an version upgrade or if it introduces submodules, you would be wise to trigger those actions in Moodle first.

To update the git submodules

git submodule init && git submodule update

To trigger a Moodle upgrade

php admin/cli/upgrade.php

Once that's settled, you run the init step.

php admin/tool/behat/cli/util.php --enable

If you had to run an upgrade, it's likely Moodle will give you a message to explicitly run the init script.

Reinstall Behat: The test environment was initialised for a different version, use:
 php admin/tool/behat/cli/init.php

Running Behat

Once that's settled, Moodle will print out the command to execute the test. Copy and paste that into your console and watch the test be executed.

Acceptance tests environment enabled, to run the tests use:
 vendor/bin/behat --config /Users/alfonso/Sites/moodledata/behat/behat/behat.yml