MoodleDocs - User contributions [en]

Question bank improvements for Moodle 4.0

2021-06-18T08:12:52Z

Tim Hunt:

{{Infobox Project
|name = Question bank improvements for Moodle 4.0
|state = Development in progress
|tracker = MDL-70329
|discussion = https://moodle.org/mod/forum/discuss.php?d=417599
|assignee = Project instigated by [[User:Thomas_Korner|Thomas Korner]], [[User:Luca_B%C3%B6sch|Luca Bösch]], [[User:Tim Hunt|Tim Hunt]], Antonia Bonaccorso. Implementation by Catalyst AU
}}
{{Moodle_4.0}}

This is a project to largely re-develop the question bank for Moodle 4.0 (if possible). The aim is to

* add some important new features, like question versioning, and making it easier to track where each question is used.
* improve how the code is organised, for example by introducing a new 'Question bank plugin' type (qbank_).
* and fix some long-standing bugs, for example the problems with question backup and restore.

== Technical overview of the plans ==

What we are planning to do is outlined in [https://moodle.org/mod/forum/discuss.php?d=417599 this forum thread]. That thread is quite long, with discussion of the plan, but the key posts which describe the plan are:
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1682674 Setting the scope]
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1683127 Question bank will be made up of plugins]
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1687624 List of the plugins that will be created initially]
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1683186 Question bank will store the version history of each question]
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1688163 How the question bank will track the places (quizzes) where questions are used]
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1685143 Some initial UI wireframes]
* [https://moodle.org/mod/forum/discuss.php?d=417599#p1705076 Question (and following discussion) about how complicated the filtering/searching system needs to be at first]

== Project support ==

This project is proceeding thanks to the support of [[Question_bank_improvements_for_Moodle_4.0#Contributors|a number of universities and other organisations]] who crowd-funded the development.

== Work-in-progress ==

In time, we will and more information here, for example links to a prototype site.

== Contributors ==

=== Contributors (initiators) ===
* The Open University
* ETH Zurich
* BFH Bern University of Applied Sciences

=== Contributors (financially) ===
* Berlin Institute of Technology (Technische Universität Berlin), Germany
* Canton of Zurich Office for Middle and vocational schools, Switzerland
* Dublin City University, Ireland
* ETH (Swiss Federal Institute of Technology) Zurich, Department of Medicine, Switzerland
* Hochschule Hannover - University of Applied Sciences and Arts, Germany *
* Johannes Kepler University Linz, Austria
* University of Applied Sciences and Arts Northwestern Switzerland, Switzerland
* Zurich University of Applied Sciences, Switzerland *

=== Contributors (workforce) ===
* Catalyst Australia
* Yvonne Wolf

=== Overflowing funds from the SEB deeper integration project ===
These institutions are credited here since they participated in the Safe Exam Browser deeper integration project. The remaining funds were allowed to be used in this project here.

* Berlin School of Economics and Law, Germany
* Neubrandenburg University of Applied Sciences, Germany
* Ruhr-University Bochum, Germany
* University of Applied Sciences Upper Austria, Austria

* Institutions funding in both SEB deeper integration as well as Question bank improvements for Moodle 4.0 project

Developer meeting June 2021

2021-06-08T19:26:41Z

Tim Hunt:

[[Developer meetings]] > June 2021 meeting

{| class="nicetable"
|-
| Date
| Tuesday 8 June 2021 at 07:00 UTC
|-
| Meeting recording
| https://moodle.org/mod/bigbluebuttonbn/view.php?id=8596
|-
| Discussion
| [https://moodle.org/mod/forum/discuss.php?d=422642 Developer meeting Tuesday 8 June 2021]
|}

== Agenda ==

# Latest #moodledev news - [https://moodle.org/user/view.php?id=2356736&course=5 Sander Bangma] (Starts at about the beginning of the recording).
# JavaScript events - [https://moodle.org/user/profile.php?id=268794&course=5 Andrew Lyons] (Starts at about 20:45 in the recording).

----

If there is any topic that you would like to present or discuss at a developer meeting, please contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

Moodle 3.11 release notes

2021-05-11T16:18:39Z

Tim Hunt: /* For developers */

[[Releases]] > {{FULLPAGENAME}}

Release date: Not yet released - scheduled for 17 May 2021

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.11%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.11].

If you are upgrading from a previous version, please see [[:en:Upgrading|Upgrading]] in the user docs.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software and operating systems up-to-date.

* Moodle upgrade: Moodle 3.6 or later
* PHP version: minimum PHP 7.3.0 ''Note: minimum PHP version has increased since Moodle 3.10''. PHP 7.4.x is supported too. [[Moodle and PHP|PHP 8.0 support]] is being implemented (see MDL-70745) and '''not ready for production''' yet.
* PHP extension '''sodium''' is recommended. It will be required in Moodle 4.2. For further details, see [https://docs.moodle.org/311/en/Environment_-_PHP_extension_sodium Environment - PHP extension sodium].
* PHP setting '''max_input_vars''' is recommended to be >= 5000 for PHP 7.x installations. It's a requirement for PHP 8.x installations. For further details, see [https://docs.moodle.org/311/en/Environment_-_max_input_vars Environment - max input vars].

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.6
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.7
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 10.2.29
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2017 (increased since Moodle 3.10)
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 11.2
| Latest
|}

==Client requirements==

=== Browser support ===

Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:

Desktop:
* Chrome
* Firefox
* Safari
* Edge

''Note: Moodle 3.10 does NOT support Internet Explorer 11.''

Safari 7 and below has known compatibility issues with Moodle 3.10.

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://www.whatsmybrowser.org/

==Warnings==

* If you have a site running on MariaDB / MySQL with many users, you may experience database issues after the upgrade step 2021042100. The upgrade attempts to drop several columns from the user table (after they were converted to new user profile fields - MDL-28452). This typically requires copying all the rows into a new tablespace and rebuilding all indexes. Which may eventually lead to time-outs and ''"MySQL server has gone away"'' errors. It should be enough and safe to simply re-run the upgrade until the upgrade step 2021042100.01 finishes successfully.

==Major features==

==Other highlights==

===For administrators===

* MDL-67748 - Web services configuration is now located in ''Site administration > Server'' section. Tokens management was improved to allow searching and filtering.

==Security issues==

A number of security related issues were resolved. Details of these issues will be released after a period of approximately one week to allow system administrators to safely update to the latest version.

==For developers==

===API changes===

* MDL-45242 - Allow user profile fields to be specified as user identity fields - New code is backwards-compatible, but report-code should be updated.

===Web service additions and updates===

* MDL-71169 - All new external functions implementation classes should use <tt>execute</tt> as the method name, in which case the <tt>methodname</tt> property should not be specified in db/services.php file

==See also==
*[[Moodle 3.10 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.11]]

[[fr:Notes de mise à jour de Moodle 3.11]]
[[es:Notas de Moodle 3.11]]

Writing acceptance tests

2021-03-26T11:35:35Z

Tim Hunt: /* Human-readable and relative dates */

== Introduction ==

This documentation gives some hints on writing behat tests for Moodle core, and for plugins. The focus of the documentation is on behat tests for plugins. Behat Features and Scenarios are written in a natural language, and should
describe how a user would interact with Moodle.

Each test consists of several stages which are categorised by the terms '''Given''', '''When''', and '''Then''':
* '''Given''': These steps allow you to perform a a test set-up. Typically Given steps are used to set configuration, create users, courses and plugin instances, and generally prepare the site for testing
* '''When''': When steps are used to get the test environment to the point at which you wish to test the conditions. This may include logging in, and then performing a range of actions like submitting an assignment and grading it for example
* '''Then''': Then steps are used to check that your plugin behaved as expected. They typically check very simple things like if certain elements or text are visible or not. For example after submitting an assignemtn in the When stage, you may have a step which checks that a notice was shown to state that the submission was successful.

These three stages match the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which is performed by Moodle between each test and does not need to be explicitly defined in your test.

Note: Each test should have only one use of '''Given''', '''When''', and '''Then'''.
See MDLSITE-3778 for information and the policy decision on why you should not have multiple Given, When, and Then steps.

Where you have several Given, When, and Then steps you should use the words '''And''', and '''But''', for example:

<code>
Given the following user exists:
| username | ccolon |
| First name | Colin |
| Last name | Colon |
| email | ccolon@example.com |
And the following course exists:
| Name | Jump Judging (Level 1) |
| Shortname | sjea1 |
When I log in as "ccolon"
And I navigate to "Site home > Jump Judging (Level 1)"
Then I should see "You are not enrolled in this course"
But I should see "Enrol now"
</code>

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

== Create your 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:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
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:
<code behat>
@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
</code>
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:
<code behat>
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 |
</code>
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.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** icon - for searching an icon by its title
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** list_item - for searching a list item which contains the specified text
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== 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:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
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
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and 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 http://php.net/manual/en/datetime.formats.php.

Especially useful are the relative formats from: http://php.net/manual/en/datetime.formats.relative.php

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in http://php.net/manual/en/function.date.php.
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

==== Writing your own steps ====

Sometimes, you will need to set up data that is specific to your plugin, or perform steps that are specific to your plugin's UI. In this case it may be necessary to [[Writing_new_acceptance_test_step_definitions|write new step definitions]], but the short version is that you define new steps as PHP methods with a special annotation inside a class called <tt>behat_plugintype_plugingname</tt> inside tests/behat/behat_plugintype_plugingname.php in your plugin.

As well as creating completely new steps, you can also extend some of the standard steps:

===== Custom selectors (<tt>... in the "..." "..."</tt>) =====

There are a load of different steps which can refer to specific items on-screen, for example

And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"

Here, 'button' and 'dialogue' are examples of selectors, and 'Submit all and finish' and 'Confirmation' are the locators which say which button or dialogue it is. When the test runs, this gets converted to an XPath expression, which is what the Behat system acutally uses to locate the right element on the page.

From Moodle 3.8 onwards, you can define new types of selector (for example <tt>core_message > Message</tt>) by implementing functions like <tt>behat_component_named_selector</tt> in your plugin's <tt>behat_plugintype_plugingname</tt> class. The detailed instructions for how to do this are in [https://github.com/moodle/moodle/blob/33da028c27607354981cd8e62ecabb7b973c6637/lib/behat/behat_base.php#L1111 the PHPdoc comments on the base class].

The reasons you might want to do this are:
* It makes your tests easier to read, which makes it easier to be sure that the test is testing the right thing, and being able to read the tests helps people understand your features.
* If the HTML structure you output changes, then you only need to update the selector definition in one place.

===== Custom navigation targets (<tt>And I am on the "..." "..." page</tt>) =====

From Moodle 3.8 onwards,there are two related steps:

Given I am on the "Quiz 1" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page

To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you you needs to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about hwo this works are given in [https://github.com/moodle/moodle/blob/a0fc902eb184cd4097c8ab453ddc57964cd2dbd4/lib/behat/behat_base.php#L1093 the PHPdoc comments on the base class].

There are two reasons why it is good to use these steps:
* You are trying to test that your feature works, not Moodle navigation. In the pase we have had many occasions when Moodle navigation changed, and lots of tests failed and had to be fixed. It is better for your tests to start on your feature. (Except, perhpas, it might be appropriate to have one test for the expected method for users to navigate to your feature.)
* It is much faster because you load fewer irrelevant pages, and in particular the normal loggi step leaves you on the Dashboard page, which is '''very''' slow to load.

===== Custom entity generators (<tt>And the following "..." exist:</tt>) =====

From Moodle 3.8 onwards, it is possible to extend the ''Given the following "entites" exist'' step to support your plugin's data generators. This avoids having to write new whole
new behat step definitions for your plugin, and allows you to re-use data generators between PHPUnit and Behat tests.

Full documentation of this process and all available options can be found in the [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/lib/behat/classes/behat_generator_base.php#L33 PHPDoc for behat_generator_base]. A core example of this can be found in [https://github.com/moodle/moodle/tree/master/mod/quiz/tests/generator /mod/quiz/tests/generator] and [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/mod/quiz/tests/behat/quiz_reset.feature#L51 quiz_reset.feature]. What follows is a simple example.

To begin, you need a [[Writing_PHPUnit_tests#Generators|generator]] in /''your''/''plugin''/tests/generator/lib.php. If you are generating a type of entity called "thing", your generator will need a method called create_thing, which accepts an object:

<code php>
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</code>

Next, you will need to define your behat generator in /''your''/''plugin''/tests/generator/behat_''your_plugin''_generator.php, with the method get_createable_entitites():

<code php>
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</code>

The 'datagenerator' value refers to the method in the generator class that we are calling, in this case ''create_thing()''. The outer array key is the entity name we will use in the behat step, in this case ''Given the following "local_myplugin > things" exist''.

Now, in your behat test, you can have a step like this, which will generate 2 ''things'', the first with the name "thing1" and the second with the name "thing2".

<code gherkin>
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

Note that this also implies that the Given, When and Then keywords should be used only once per scenario.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Question bank improvements for Moodle 4.0

2021-03-09T13:20:59Z

Tim Hunt:

{{Infobox Project
|name = Question bank improvements for Moodle 4.0
|state = Development in progress
|tracker = MDL-70329
|discussion = https://moodle.org/mod/forum/discuss.php?d=417599
|assignee = Project instigated by Thomas Korner, Luca Bösch, [[User:Tim Hunt|Tim Hunt]], Antonia Bonaccorso. Implementation by Catalyst AU
}}

This is a project to largely re-develop the question bank for Moodle 4.0 (if possible). The aim is to

* add some important new features, like question versionning, and making it easier to track where each question is used.
* improve how the code is organised, for example by introducing a new 'Question bank plugin' type (qbank_).
* and fix some long-standing bugs, for example the problems with question backup and restore.

The project has been explained in detail in [https://moodle.org/mod/forum/discuss.php?d=417599 this forum thread], so for more details, please read that.

== Project support ==

This project is proceeding thanks to the support of an number of universities and other organisations who crowed-funded the development.

== Work-in-progress ==

In time, we will and more information here, for example links to a prototype site.

{{Moodle_4.0}}

Question bank improvements for Moodle 4.0

2021-03-09T12:51:00Z

Tim Hunt: Created page with "{{Infobox Project |name = Question bank improvements for Moodle 4.0 |state = Development in progress |tracker = MDL-70329 |discussion = https://moodle.org/mod/forum/discuss.ph..."

{{Infobox Project
|name = Question bank improvements for Moodle 4.0
|state = Development in progress
|tracker = MDL-70329
|discussion = https://moodle.org/mod/forum/discuss.php?d=417599
|assignee = Project instigated by Thomas Korner, Luca Bösch, [[User:Tim Hunt|Tim Hunt]], Antonia Bonaccorso. Implementation by Catalyst AU
}}

This is a project to largely re-develop the question bank for Moodle 4.0 (if possible). The aim is to

* add some important new features, like question versionning, and making it easier to track where each question is used.
* improve how the code is organised, for example by introducing a new 'Question bank plugin' type (qbank_).
* and fix some long-standing bugs, for example the problems with question backup and restore.

The project has been explained in detail in [https://moodle.org/mod/forum/discuss.php?d=417599 this forum thread], so for more details, please read that.

== Project support ==

This project is proceeding thanks to the support of an number of universities and other organisations who crowed-funded the development.

== Work-in-progress ==

In time, we will and more information here, for example links to a prototype site.

Moodle 4.0 navigation improvements

2021-02-25T14:36:52Z

Tim Hunt:

{{Infobox Project
|state = In progress
|name = Update general Moodle navigation
|tracker = MDL-69588 (epic)
|discussion = [https://moodle.org/mod/forum/discuss.php?d=418328 Navigation for Moodle 4.0]
|assignee = Team Alpha
}}
{{Moodle 4.0}}

== Introduction ==

With the incoming release of Moodle 4.0, it is our desire to improve the user experience surrounding the navigation of courses, modules and other key areas by reducing the cognitive load upon users when navigating. These improvements will only be made to the existing primary Moodle theme: Boost. Whilst the primary focus is upon Boost it is our goal that the theme Classic will retain its current functionality.
The overall aim of this project is to create a simplified navigation hierarchy where:
* Users no longer feel overwhelmed by numerous pathways to get to a single destination
* Navigation pathways follow common patterns all throughout Moodle
* Navigation options presented to the user are contextually relevant; so that users intuitively and quickly learn how to get to where they need to be
* Navigation has a consistent look and feel between desktop sized viewports & mobile sized viewports
The focus of this project is on the student and teacher navigation experience.

== Prototype / mock-ups ==

=== Primary navigation ===

Across all of Moodle the header of the site will be changed for 4.0 with important navigation elements being rendered within the header of Moodle.
With this change to navigation new active and hover states will be created to inform users of where they currently are and where they are navigating to at a glance.

When the amount of navigation items exceeds the width of the viewport width then a new dynamic menu item will appear that navigation elements overflow into.

On mobile devices it is expected that within Moodle the primary navigation will be rendered as a navigation drawer in the same fashion as the current navigation drawer.

The image below shows a prototype for Moodle 4.0 with navigation within the header for the page, it also includes custom menu elements to demonstrate that existing functionality is being accounted for.

==== Desktop primary navigation ====

[[File:Primary.png]]

==== Mobile primary navigation ====

Primary navigation (mobile device inactive)
[[File:Primary_mobile_inactive.png]]

Primary navigation (mobile device active)
[[File:Primary_mobile_active.png]]

=== Secondary navigation ===

Navigation items will now appear as tabs within the context header (Course header, Site admin header, etc...) and similar to the primary navigation the active element will have an indicator below the active tab and have hover styling that indicates the potential tab item that’ll be navigated to.

Also similar to the primary navigation a dynamic “More” menu will be implemented to accommodate navigation elements when the viewport width reduces to a point where elements can not feasibly be shown within the menu area.

The below image shows the secondary navigation within the page header, this will look similar to the above primary navigation image.

==== Desktop secondary navigation ====

[[File:Secondary.png]]

=== Page header (Context header) ===

Work here will primarily focus on user interactions with the context header such as automatic hiding and displaying of elements depending on the users' scrolling and page position. Other changes will include rearranging elements, modifying font sizing, weight and spacing around the current page name.

The below image shows the page header on a mobile device as the desktop viewport examples can be seen in the prior images.

==== Mobile view page header ====

[[File:Mobile_context.png]]

== User stories ==

These are the user stories that this project aims to address.

=== For the student ===

{| class="wikitable" border="1"
|-
! '''Student user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a learner, I want to easily find the menu item, so that I can move between courses and activities.
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed.
|-
| As a learner, I want to view my grades within a course, so that I can review my grades or find actionable items
| Within the course context I should be able to click straight through to my grade overview
|-
| As a learner, I can want to view my grades for a forum activity, so that I can discover if my participation is satisfactory
| Within a forum activity I should still have the ability to view my grade using the existing forum grading functionality
|}

=== For the course creator / teacher ===

{| class="wikitable" border="1"
|-
! '''Course creator / teacher user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a teacher, I want to easily find the menu item, so that I can move between courses and activities
| I should be able to easily see my list of courses in a predictable place and be able to jump from one course to another at speed
|-
| As a teacher, I want to edit a courses' settings, so that I can improve my learners experience
| I should be able to within a course context easily go to my courses’ settings and make changes
|-
| As a teacher, I want to easily edit a course module, so that I can deliver my course content in my preferred method
| Within a course module, I should be able to easily navigate to the module settings to make required changes
|-
| As a teacher, I want to view the reports for a course, so that I can any actionable items
| Within a course I should be able to easily navigate to the reporting area within a course
|-
| As a teacher, I can quickly find an overview of learners' grades, so that I can find learners to assist
| As a teacher I can quickly find the learners grades without getting lost
|-
| As a teacher, I can need to grade a learners forum activity, so that I can provide my learners with feedback on their activity
| Within a forum module instance I can open the forum grading functionality and grade users’ participation within the forum
|-
| As a teacher, I can turn editing on within a course, so that I can add new content or modify existing content with a course
| I can easily turn on course editing within the course to add new modules
|}

=== For the administrator ===

{| class="wikitable" border="1"
|-
! '''Administrator user stories'''
! '''Acceptance criteria / confirmation'''
|-
| As a site admin, I want to modify my Moodle instances’ settings, so that I can deliver a better experience for my users
| Links to the site administration settings still appear in easily locatable locations for site administrators
|}

=== Common user stories ===

{| class="wikitable" border="1"
|-
! '''User story'''
! '''Acceptance criteria / confirmation'''
|-
| As any user, I can see other participants within a course, so that I can either enrol learners or find fellow learners within a course
| Within the course I can easily find a navigation item for participants
|-
| As any user, I can use the secondary navigation whilst only using user accessibility tools, so that I can access the site
| The new navigation meets WCAG 2.1 AA & can be used with screen readers & other assistive technologies
|-
| As any user, I want to see an overview of all of my courses, so that I can navigate around the site
| I can navigate to a dashboard of sorts that contains the courses I am currently enrolled in or have access to
|-
| As any user, I want to easily navigate to an enrolled course, so that I can view my content
| I can easily find my desired course to review its content
|-
| As any user, I want to quickly navigate to the site home page, so that I can find other relevant content
| I am able to navigate to the sites home easily & quickly
|-
| As any user, I want to use the primary navigation whilst only using user accessibility tools, so that I can access the site
| The new navigation meets WCAG 2.1 AA & can be used with screen readers & other assistive technologies
|-
| As any user, I want to navigate back to the course with the navigation bar, so that I can quickly go to a different piece of learning content
| As any user, I should be able to use the context header bar within a module to navigate back to the start of the course
|-
| As any user, I want to navigate back to the section the module is in from the navigation bar, so that I can find other pieces of learning content that are similar to the current content I am reviewing
| As any user, I should be able to use the context header bar within a module to navigate back to the section of the course that the current module is placed in
|-
| As any user, I can search a forum that I am in, so that I can find relevant posts or discussions before making a new post
| I can still search forums in a similar or identical way as I currently can (pre Moodle 4.0)
|}

== Code architecture ==

Navigation views are a way to distinguish from the actual navigation of the system. Global and settings navigation are a true source of the internal navigation system. The views are for display purposes and can be interpreted by the different themes as they please.

As a developer you can register your new navigation item against different views for example
* 'primary' navigation items across the top of the page with the site header
* 'secondary' navigation items across the top of the page content within the context header

As seen in the diagram below, the current idea is to create a view based class system where *_navigation_view classes extend the existing navigation_node class. The idea behind this new structure is that the system and third party theme developers can easily fetch a representation of the current navigation within a given context and immediately render out only the view they want as opposed to fetching the entire navigation for the page.

New classes that extend existing classes
[[File:view_diagram.jpg

=== Technical design of *_navigation_view ===

The primary & secondary navigation view classes are representations of the navigation within a given context. The instances of these navigation views will be capable of accepting navigation items appended to them within plugins; however, plugins will not be able to remove existing navigation_node‘s.

Custom label added via plugin
[[File:Primary.png]]

An example of the above would be the following where "Custom label" has been added by an arbitrary plugin to the primary navigation of a Moodle instance:

Note: In this example we will be using simple strings, During implementation the navigation_node class should be used.

$primarynav = $PAGE->secondarynavigationview
$customlabel = $secondnav->register('Custom label')

To add further navigation items underneath the "Custom label" navigation item you could then do the following:

$customlabel->register_child('Secondary label')
$doclabels = $customlabel->register_child('Docs')
$doclabels->register('Indepth docs')

After the following the following would be represented within the primary navigation after the default navigation items:

* Custom label
** Secondary label
** Docs
*** Indepth docs

=== Consideration given to third party plugins ===
It is highly likely that the new navigation classes will be using functions from settings_navigation such as load_module_settings(). This provides access to callbacks that are already implemented for both course module plugins and local plugins that modify what navigation_node’s populate the either navigation view.

This means that both core and third party Moodle theme plugins will not be able to mutate / modify any received new navigation views as the only accessible functions publicly defined would be to fetch a representation of the navigation to be output by the theme in a template.

The process for calling these new navigation views is similar to existing methods of calling navigation, there'll be a new properties added to the lib/pagelib.php called primarynavigationview & secondarynavigationview. These properties will be used in conjunction with magic_get_*navview() to create a new primary_navigation_view or secondary_navigation_view and trigger the initialization method.
To view a similar calling method, view how the navigation is called within any of the columns files within the boost theme where it calls flatnav.

=== Further reading ===
More technical discussion can be found within issues in the navigation epic MDL-69588 or in the specification document (releasing soon)

Github actions integration

2021-02-20T17:00:24Z

Tim Hunt: /* Moodle plugins */

== Moodle core ==

=== Background ===

Moodle is regularly tested against a matrix of Databases, PHP Versions, and operating systems, however many developers do not have the resources available to run on many of these combinations before pushing an issue for integration as they are time-consuming to both set up and to run.

There are many Continuous Integration tools available to developers, and [https://github.com/features/actions GitHub Actions] is just one of those available to the Open Source community.

Since November 2020 (Moodle 3.5.16 and up), Moodle includes a GitHub Actions configuration file in its repository. This configuration file configures and controls a GitHub build across a matrix of testing environments. This allows developers pushing patches to Moodle to have their code unit tested before it reaches integration. The hope is that the availability of this integration should reduce the number of unit test failures seen during Integration.

Note: Moodle HQ uses the Jenkins CI platform and this should be seen as the [https://ci.moodle.org/ canonical CI server for Moodle]. The GitHub Actions integration aims is to provide early warning to developers of any issues with their code.

=== Usage ===

GitHub Actions are available and enabled by default for all public repositories @ GitHub. You can enable or disable them going to your moodle.git clone page, then settings tab -> actions . Please use the "Allow all" option as far as the integration reuses actions from different sources.

[[File:enable_disable_github_actions.png|Enabling and disabling GitHub Actions for your repos]]

For the purpose of this documentation, it is assumed that you are pushing to a public Moodle repository on GitHub. Other integrations are supported, but the service available from GitHub Actions is only available to github public repositories.

=== How do I start a build? ===

Whenever you push a change to any branch in your repository... a build will be queued and executed. You can see how all your builds are progressing by visiting your moodle.git clone page at GitHub, then selecting the actions tab. From there you can filter by branch, by status, access to every build, see failures, relaunch jobs...

[[File:actions_dashboard.png|GitHub Actions "dashboard"]]

You will receive notifications (by email or web) whenever a build finish (can be configured from your account notification settings). Also, if your branches match the branch names in any issue in the Tracker, you will get there the corresponding pass/fail badges [[File:github_passing.png|GitHub passing badge]]. Clicking on them you will access straight to the job details @ GitHub.

And that's all, pretty nice, simple and effective.

== Moodle plugins ==

See [https://moodlehq.github.io/moodle-plugin-ci/#github-actions the instructions in the Moodle Plugin CI repository].

== See also ==

* [[Travis integration]]: For information about the, also supported, integration with Travis CI facilities.

[[Category:Developer tools]]

Travis integration

2021-02-19T21:03:40Z

Tim Hunt:

Given the two notes beliw, you probably don't want to read this page. [[Github actions integration]] is much more likely to be what you want.

<div class="note">Travis [https://mailchi.mp/3d439eeb1098/travis-ciorg-is-moving-to-travis-cicom has announced] that '''travis-ci.org will be closed down completely on December 31st 2020''', with travis-ci.com becoming the unified place for all projects. More information can be found at:
* [https://docs.travis-ci.com/user/migrate/open-source-repository-migration Migrating repositories to travis-ci.com]
* Moodle Tracker: MDLSITE-6246</div>
<div class="note">Travis [https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing has announced], November 2, 2020, that '''travis-ci.com won't be (unlimitedly) free anymore''', with everybody getting some credits (processing time) once and, after using them, you must change to some of their (paid) plans. Few weeks later, November 24, 2020, [https://blog.travis-ci.com/oss-announcement they have published an update] specifically for Open Source. There, they recommend to contact them ''"for anything relating with your open source account"''. Up to you!
More information can be found at:
* Moodle Tracker: MDL-70265</div>

== Moodle core ==

=== Background ===

Moodle is regularly tested against a matrix of Databases, PHP Versions, and operating systems, however many developers do not have the resources available to run on many of these combinations before pushing an issue for integration as they are time-consuming to both set up and to run.

There are many Continuous Integration tools available to developers, and Travis-CI is just one of those available to the Open Source community.

Since version 3.0, Moodle includes a Travis configuration file in its repository. This configuration file configures and controls a Travis build across a matrix of testing environments. This allows developers pushing patches to Moodle to have their code unit tested before it reaches integration. The hope is that the availability of this integration should reduce the number of unit test failures seen during Integration.

Note: Moodle HQ uses the Jenkins CI platform and this should be seen as the [https://ci.moodle.org/ canonical CI server for Moodle]. The Travis integration aims is to provide early warning to developers of any issues with their code.

=== Usage ===

Travis-CI is available and is usually configured to run automatically when pushing code, but it must be configured before first use.

For the purpose of this documentation, it is assumed that you are pushing to a public Moodle repository on GitHub. Other integrations are supported, but the service available from Travis is only available to public repositories.

=== Setup ===

# [https://travis-ci.com/auth Sign in to Travis CI] using your GitHub account
# Once you’re signed in, and the initial synchronisation of your GitHub repositories has completed, go to your [https://travis-ci.com/profile profile page]
# Enable Travis CI for your clone of the Moodle repository [[File:moodle-travis-enable.png]]
# Click on the cog icon to configure the Integration
# Ensure that "Build pushed branches" is enabled [[File:moodle-travis-settings-2020.png]]
# Email notifications will be sent by default to the committer and the commit author. If you want to turn off email notifications for this repository, you can define an environment variable with name MOODLE_EMAIL and "no" as value.
# By default, the following jobs will be executed for each branch sent to github:
## GRUNT: 1 job that will check that all your javascript and scss has been properly built (see [[Grunt]]) and is part of the patch.
## CITESTS: 1 job that will perform a lightweight linting of your branch.
## PHPUNIT: 1 job that will run all the unit tests on your branch (using the lowest PHP version supported by the branch and PostgreSQL as database).
# If you want to change those defaults, you can use the following environment variables:
## MOODLE_DATABASE: With value "mysqli" to switch your runs to that database. With value "all" to run both PostgreSQL and MySQL unit tests.
## MOODLE_PHP: With value "all", to run the unit tests both with the lowest and the highest PHP versions supported by the branch.
Note that adding more jobs will increase the time needed (and the credits consumed) for processing each branch, so be careful picking your fav configuration.
[[File:environment_variables.png|Define an environment variable]]

=== How do I start a build? ===

It won't build immediately after setup. Builds start automatically when you push a change.

== Moodle plugins ==

See [https://moodlehq.github.io/moodle-plugin-ci/ Moodle Plugin CI repository] for setup instructions.

Related discussions:
* [https://moodle.org/mod/forum/discuss.php?d=323384 Adding Travis CI support into your plugin]
* [https://moodle.org/mod/forum/discuss.php?d=389744 Recent Travis-CI issues with plugins]

=== Ignoring files and folders ===

For some of the code analysis tools, it is important to ignore some files within the plugin because they might not be fixable, like a third party library. The all code analysis commands in this project ignore files and directories listed in the thirdpartylibs.xml plugin file. See https://docs.moodle.org/dev/Plugin_files#thirdpartylibs.xml for more info.

==== Ignoring files ====

Specifically for the codechecker command, you can ignore a single line, a section of a file or the whole file by using specific PHP comments. For details see this [[CodeSniffer]] wiki page.
In addition, you can ignore additional files by defining IGNORE_PATHS and/or IGNORE_NAMES environment variables in your .travis.yml file. These environment variables wont work for Grunt tasks, but will for everything else. Example:
<code php>
env:
global:
- MOODLE_BRANCH=MOODLE_35_STABLE
- IGNORE_PATHS=vendor/widget,javascript/min-lib.js
- IGNORE_NAMES=*-m.js,bad_lib.php
matrix:
- DB=pgsql
- DB=mysqli
</code>
Both environment variables take a CSV value. For IGNORE_PATHS, it takes relative file paths to ignore. File paths can be a simple string like foo/bar or a regular expression like /^foo\/bar/. For IGNORE_NAMES, it takes file names to ignore. File names can be a simple string like foo.php, a glob like *.php or a regular expression like /\.php$/.

If you need to specify ignore paths for a specific command, then you can define additional environment variables. The variable names are the same as above, but prefixed with COMMANDNAME_. Example:

<code php>
env:
global:
- MOODLE_BRANCH=MOODLE_35_STABLE
- IGNORE_PATHS=vendor/widget,javascript/min-lib.js
- IGNORE_NAMES=*-m.js,bad_lib.php
- PHPUNIT_IGNORE_PATHS=$IGNORE_PATHS,cli
matrix:
- DB=pgsql
- DB=mysqli
</code>
In the above example, we are adding the cli path to our ignore paths for the PHPUnit command (this is also how you can ignore files for code coverage). Please note that this is a complete override and there is no merging with IGNORE_PATHS and IGNORE_NAMES. So, in the above, the PHPUnit command would not ignore the file names defined in IGNORE_NAMES.

== See also ==

* [[Github actions integration]]: For information about the, also supported, integration with GitHub Actions.

[[Category:Developer tools]]

Moodle 3.9.4 release notes

2021-01-19T12:54:28Z

Tim Hunt:

[[Releases]] > {{FULLPAGENAME}}

Release date: 18 January 2021

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.9.4%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.9.4].

==Warning==
If you use a custom course format, and your courses have a lots of sections, then be aware of the MDL-69431 change. Course formats used to have a method get_max_sections which used to be ignored, so you probably never implemented it, so you get the default return value of 52. With Moodle 3.9.4 you wont be able to edit activties in your big courses until you have fixed your custom course format plugin.

==General fixes and improvements==
* MDL-54907 - Automatically submitted quiz attempts: finish time is set to when cron ran, not when the attempt ended
* MDL-69964 - The "Select all X users" button doesn't activate the drop-down menu in Participants Page
* MDL-68896 - SCORM error in Chrome because of "XHR in page dismissal" policy change
* MDL-67623 - Course overview (my courses block) pagination is broken beyond the second page
* MDL-56119 - Rubric display layout issue, after students feedback is released
* MDL-50955 - Lesson module error on save - Cannot find grade item for 'lesson'
* MDL-65941 - Redis server issues break cache configuration page
* MDL-70157 - AWS Aurora MySQL support for Moodle (backport of MDL-58931)
* MDL-70285 - The MDL-69687 upgrade step kills large databases
* MDL-69526 - Custom field values in course overview block follow incorrect order
* MDL-65852 - Non-editing teacher should be able to download course participants list
* MDL-70265 - Reduce the number of phpunit runs in core's .travis.yml
* MDL-70386 - Illegible css coloring of correct/incorrect div
* MDL-69930 - Duplication items in drag-onto-image question
* MDL-70276 - Add support for github actions to moodle.git
* MDL-70355 - Multilang Filters not applied to Calendar block
* MDL-70063 - [Youtube Plugin] Selecting a category results in <data could not be obtained> error
* MDL-67513 - View conversation link does not work when grading in full screen mode
* MDL-70558 - Available language packs unsorted, difficult to locate
* MDL-69868 - H5P corrupts USER object, causing forum error
* MDL-70426 - Drag-drop markers questions: infinite markers keep duplicating
* MDL-70065 - Quiz add questions from question bank: problem with paging & show all
* MDL-62707 - codingerror in Global Search when "search within enrolled courses only" is set
* MDL-70148 - Write new keyboard steps for Behat
* MDL-69955 - Question type Drag and Drop: drop zone disappear in special case
* MDL-70320 - Incorrect HTML escaping on the override permissions screen
* MDL-70261 - Upload Courses tool breaks on locked custom fields
* MDL-70436 - On mobile, the Quiz confirmation modal has it's close button cut off
* MDL-70373 - Atto HTML editor lacks border outside Moodle forms (e.g. Essay questions)
* MDL-70374 - Layout of multiple choice questions not well aligned
* MDL-70520 - Moodle upgrade resets scheduled tasks lastruntime
* MDL-70117 - PDF dataformat export: content can overflow when page headers are involved
* MDL-70072 - Date in message system (always in Gregorian)
* MDL-70248 - Drag and Drop onto images: Drop zones have UI issue in Editing form
* MDL-70080 - Users should be able to contact the site's support via the Moodle App (Backport of MDL-69810)
* MDL-67636 - Locking grade category exposes hidden item grades on user report
* MDL-70352 - Modal forms stay on the screen if you have multiple modals on one page
* MDL-70567 - Task logs page doesn't respect result filter when moving through the pagination
* MDL-70009 - Course with H5P element in content bank can not be deleted by Manager/Teacher role (with appropriate rights)

==Accessibility improvements==
* MDL-69841 - Edit Quiz, click on help icon under review options group will check / uncheck the checkbox
* MDL-69422 - HTML validation and accessibility problems on database export page
* MDL-69301 - Focus order in tabs
* MDL-70094 - Question preview: Technical info section expands if you click the help icon there

==Security improvements==
* MDL-69877 - Set up a security.txt file in Moodle LMS

==Security fixes==

Details of any security issues will be released after a period of approximately one week to allow system administrators to safely update to the latest version.

==See also==
*[[Moodle 3.9.3 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.9]]

[[fr:Notes de mise à jour de Moodle 3.9.4]]
[[es:Notas de Moodle 3.9.4]]

Moodle 3.8.6 release notes

2020-11-23T21:11:45Z

Tim Hunt:

'''This version of Moodle is no longer supported for general bug fixes.''' You are encouraged to [[:en:Upgrading|upgrade]] to a supported version of Moodle.

[[Releases]] > {{FULLPAGENAME}}

Release date: 9 November 2020

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.8.6%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.8.6].

==Warning==

If you have a large database, the upgrade step added in MDL-69687 may be very, very slow. To avoid excessive down-time when you grade, you may want to test for this. A fix is being developed in MDL-70285.

==General fixes and improvements==
* MDL-68722 - Atto Equation Editor Symbols missing
* MDL-68070 - Messaging breaks when "Personal messages between users" is disabled
* MDL-68900 - Attempting to grade forums outside of their display period causes invalid response value error
* MDL-65792 - Timed/Scheduled Posts are displaying create/modified time instead of release time
* MDL-69667 - Competencies count always 0 in competencyframeworks
* MDL-69772 - Incorrect 'allcountrycodes' field prevents country selection during registration
* MDL-69641 - Fix Course gradebook slow query due to cross join on full user table (backport of MDL-69190)
* MDL-62387 - Cohort sync dropdown contains redundant entries
* MDL-69342 - 'Delete picture' checkbox deletes also the new profile picture when editing profile
* MDL-69359 - Add option to show only contributed plugins in uninstall script (backport of MDL-69260)
* MDL-67654 - Forum inline reply does not use formchangechecker
* MDL-69791 - Grader report doesn't show an error message when an invalid grade is entered in AJAX mode
* MDL-69818 - Restoring a feedback activity doesn't restore item dependency
* MDL-67650 - Forced $CFG config checkbox, select, textarea are not disabled in GUI
* MDL-68438 - Changing notification email format fails if messaging is disabled
* MDL-68284 - Locking invisible quiz in gradebook setup makes it visible (but only on gradebook setup page)
* MDL-69805 - Database activity shows the comments option even if comments are disabled at site level

==Accessibility improvements==
* MDL-65074 - Quiz navigation buttons use part of btn-secondary styles, can disappear
* MDL-70004 - Invalid role attribute in the label for the "Clear my choice" option
* MDL-69392 - Colour contrast issues in quiz
* MDL-68766 - Login form: "Log in using your account on:" should be h3, not h6
* MDL-69395 - Insufficient colour contrast between form control borders and background
* MDL-69649 - Missing labels in restore page

==For developers==
* MDL-52407 - Travis: Start sending e-mail notifications

==Security improvements==
* MDL-68292 - admin/modules.php exposes CSRF token (sesskey) in url
* MDL-69014 - User preferences not removed when tours are deleted
* MDL-69807 - Editing a block exposes the CSRF token (sesskey) in the url

==Security fixes==

* [https://moodle.org/mod/forum/discuss.php?d=413935 MSA-20-0016] Teacher is able to unenrol users without permission using course restore
* [https://moodle.org/mod/forum/discuss.php?d=413936 MSA-20-0017] Privilege escalation within a course when restoring role overrides
* [https://moodle.org/mod/forum/discuss.php?d=413938 MSA-20-0018] Some database module web services did not respect group settings
* [https://moodle.org/mod/forum/discuss.php?d=413939 MSA-20-0019] tool_uploadcourse creates new enrol instances unexpectedly in some circumstances
* [https://moodle.org/mod/forum/discuss.php?d=413941 MSA-20-0021] The participants table download feature did not respect the site's "show user identity" configuration

==See also==
*[[Moodle 3.8.5 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.8]]

[[fr:Notes de mise à jour de Moodle 3.8.6]]
[[es:Notas de Moodle 3.8.6]]

Moodle 3.10 release notes

2020-11-23T21:11:34Z

Tim Hunt:

[[Releases]] > {{FULLPAGENAME}}

Release date: 9 November 2020

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.10%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.10].

If you are upgrading from a previous version, please see [[:en:Upgrading|Upgrading]] in the user docs.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software and operating systems up-to-date.

* Moodle upgrade: Moodle 3.5 or later
* PHP version: minimum PHP 7.2.0 ''Note: minimum PHP version has increased since Moodle 3.8''. PHP 7.3.x and 7.4.x are supported too. See [[Moodle and PHP]] for details.
* PHP extension '''mbstring''' is required (it was previously only recommended)

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.6 (increased since Moodle 3.9)
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.7 (increased since Moodle 3.9)
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 10.2.29 (increased since Moodle 3.8)
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2012
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 11.2
| Latest
|}

==Client requirements==

=== Browser support ===

Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:

Desktop:
* Chrome
* Firefox
* Safari
* Edge

''Note: Moodle 3.10 does NOT support Internet Explorer 11.''

Safari 7 and below has known compatibility issues with Moodle 3.10.

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://www.whatsmybrowser.org/

==Warning==

If you have a large database, the upgrade step added in MDL-69687 may be very, very slow. To avoid excessive down-time when you grade, you may want to test for this. A fix is being developed in MDL-70285.

==Major features==

===Download course content===
* MDL-69548 - Add ZipStream library to core
* MDL-69549 - Create course content export API
* MDL-69559 - Course content download - add site admin and course level settings, implement in course user interface

===Payment subsystem===
* MDL-69166 - Add payment as subsystem supporting payment gateways

===H5P updates and improvements===
* MDL-69087 - Add the option to personalize H5P styles
* MDL-69207 - Add library file caching to h5p
* MDL-69174 - Method of saving embedded H5P content grades in the gradebook
* MDL-69520 - Add Example and Tutorial links to the H5P editor
* MDL-68909 - Clean up temporary H5P editor files

===Content bank===
* MDL-69269 - Download content from the content bank
* MDL-69270 - Replace content file from content bank
* MDL-68688 - Add a notification when the content bank is empty
* MDL-68975 - Add the author to the content bank "file details" view

===Quiz and questions===
* MDL-45002 - New quiz completion option: At least one (or N) attempt completed
* MDL-66587 - Scrolling quiz timer
* MDL-68562 - Qtype_essay: Adding file-size limit to the attachment files

===Accessibility improvements===
* MDL-68390 - WCAG 4.1.2: aria-hidden elements contain focusable elements
* MDL-67687 - Add Behat step to verify WCAG A and WCAG AA compliance

===External tool (IMS-LTI)===
* MDL-67473 - LTI Advantage: Content Item flow to support creating multiple links
* MDL-67301 - Implement LTI 1.3 Dynamic Registration
* MDL-66934 - LTI: support substitution parameter for course history

===Usability improvements===
* MDL-28501 - For folder resource, allow files to be opened in the browser rather than being downloaded
* MDL-65959 - Let users define their preferred backpack
* MDL-56041 - Cleanup custom 404 page and more easily support custom 50x error pages
* MDL-69192 - Assignment grading page: "Changes saved" should not be modal dialog
* MDL-33981 - Add ability to copy to Equella repository
* MDL-60621 - Improvement of modal UI when modal exceeds the height of the browser
* MDL-53966 - Lesson: Allow maximum number of attempts to be unlimited
* MDL-69613 - Grade report single view - confirm message if Override None is selected
* MDL-69454 - Use a consistent search input field across all Moodle searches
* MDL-67278 - Use autocomplete widget for course category selector
* MDL-68107 - Boost: Make images in topic descriptions scale with the browser window
* MDL-68702 - Option to not include legacy course files in backup and restore process
* MDL-69630 - Social activity course format should allow for using the activity chooser
* MDL-63387 - Show original role name of renamed roles when enrolling users

==Other highlights==

===Functional changes===
* MDL-59510 - Keep OAuth 2 connections alive across users' sessions
* MDL-66716 - Timeline block shows incorrect date of due items
* MDL-48391 - tool_uploadcourse should check if enrolment method can be disabled/deleted
* MDL-69739 - User tours: Add tour-level CSS selector
* MDL-69464 - Option to allow HTML in the page headings (skip applying format_string)
* MDL-67419 - Set language in user profile during account auto-creation based on browser language instead of admin setting
* MDL-37745 - Control the display of available spaces in limited choices

===For administrators===
* MDL-67211 - Tasks: Show information about running tasks, allow tasks to be disabled
* MDL-45849 - New capability to self enrol in course
* MDL-65451 - User upload via CLI
* MDL-69307 - Add CLI script to restore a course from backup file
* MDL-69583 - Add import to tool_customlang
* MDL-69582 - Add export to tool_customlang
* MDL-69260 - Add option to show only contributed plugins in uninstall script
* MDL-69513 - Add ability to add dkim signatures using phpmailer
* MDL-69265 - Have a way to append fixed arbitrary headers to all emails
* MDL-69600 - Expose divertallemailsto and divertallemailsexcept in the admin settings GUI
* MDL-69718 - Add support for terabytes and petabytes in the display_size function

===Mobile===
* MDL-65976 - Add a new message provider for course completed
* MDL-68406 - Add option for "sign-out" only for the Moodle app
* MDL-68797 - Config setting for mobile file type exclusion list
* MDL-67841 - Update mobile app connected message so it is not misleading when the user has not used the app for a time
* MDL-69810 - WebService: Users should be able to contact the site's support via the Moodle App

===Performance===
* MDL-69760 - Performance improvement on Moodle Event table
* MDL-60583 - external_tokens table will benefit from index on token field
* MDL-68665 - Improve cacheability of assignfeedback_editpdf/stamps
* MDL-64818 - Improve efficiency of blocks_for_region()
* MDL-69746 - tool_replace: additional skip tables
* MDL-68729 - Search: Allow query on one Solr server and indexing on another
* MDL-68726 - Search: Stop Solr 'optimize' behaviour
* MDL-68690 - Search: Allow Solr to add documents in batches

==Security improvements==
* MDL-66222 - Add admin options for how to handle detected viruses
* MDL-68820 - Add a Referrer-Policy header setting to the security admin settings

==For developers==
* MDL-58931 - AWS Aurora MySQL support for Moodle
* MDL-41492 - Allow alternate MUC cache config class (eg allow setup in pure $CFG / config.php)
* MDL-38350 - PHP Warning when purging all caches: race condition?
* MDL-68874 - New optional SQL debug mode which instruments SQL with the calling PHP code
* MDL-69117 - Improve theme designer mode - part 2
* MDL-67673 - Upgrade phpunit to 8.5.x
* MDL-68564 - Update before_footer hook to allow for output to be added to the page
* MDL-69050 - Rename terms to use inclusive language
* MDL-65743 - Upgrade XMPPHP to latest version
* MDL-69418 - Allow plugins to attach data to grade items during backup and restore
* MDL-68928 - Add a way to decide what plugin will show in the activity chooser footer

===Web service additions and updates===
* MDL-67306 - Create API for grade category (gradebook)
* MDL-55971 - Dataformat - Store to filearea support
* MDL-69486 - Add user idnumber and gradeitem idnumber to gradereport_user_get_grade_items webservice
* MDL-63805 - New Web Service mod_glossary_update_entry
* MDL-69776 - New Web Service core_files_delete_draft_files
* MDL-69283 - Allow specifying a timezone when calling WebServices
* MDL-63806 - New Web Service mod_glossary_delete_entry
* MDL-68845 - Create new Web Service for retrieving the user calendar via iCal
* MDL-69577 - Add courseId and forumId info to mod_forum_get_discussion_posts web service

===Deprecations===
* MDL-67594 - Deprecate supports_recursion() & extend_lock() in the Lock API
* MDL-67735 - Remove Bootstrap 2 and Bootstrap 4 alpha compatibility files
* MDL-69238 - Final removal of lib/coursecatlib.php
* MDL-63261 - Final deprecation of web services in message/externallib.php
* MDL-62982 - Remove the lib/form/htmleditor.php element
* MDL-63254 - Final deprecation of the events message_contact_blocked and message_contact_unblocked
* MDL-63004 - Final deprecation: I navigate to "ITEM" node in "MAINNODE > PATH" behat step
* MDL-55192 - Final deprecation of add_to_log()
* MDL-63167 - Final deprecation of the gradingform_provider interface

===Component API updates===

* [https://git.in.moodle.com/moodle/moodle/blob/master/admin/tool/log/upgrade.txt admin/tool/log/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/backup/upgrade.txt backup/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/badges/upgrade.txt badges/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/cache/upgrade.txt cache/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/calendar/upgrade.txt calendar/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/format/upgrade.txt course/format/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/course/upgrade.txt course/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/grade/grading/form/upgrade.txt grade/grading/form/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/h5p/upgrade.txt h5p/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/lib/upgrade.txt lib/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/message/upgrade.txt message/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/forum/upgrade.txt mod/forum/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/glossary/upgrade.txt mod/glossary/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/lti/upgrade.txt mod/lti/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/mod/quiz/upgrade.txt mod/quiz/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/question/behaviour/upgrade.txt question/behaviour/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/search/upgrade.txt search/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/theme/upgrade.txt theme/upgrade.txt]
* [https://git.in.moodle.com/moodle/moodle/blob/master/webservice/upgrade.txt webservice/upgrade.txt]

==See also==
*[[Moodle 3.9 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.10]]

[[fr:Notes de mise à jour de Moodle 3.10]]
[[es:Notas de Moodle 3.10]]

Moodle 3.9.3 release notes

2020-11-23T21:10:38Z

Tim Hunt:

lib/formslib.php Form Definition

2020-11-09T20:06:23Z

Tim Hunt: /* autocomplete */

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>
===Passing parameters to the Form===

The constructor for ''moodleform'' allows a number of parameters including one (''$customdata'') to permit an array of arbitrary data to be passed to your form.

For example, you can pass the data "$email" and "$username" to the Form's class for use inside (say) the definition.
<code php>
...
$mform_simple = new simplehtml_form( null, array('email'=>$email, 'username'=>$username ) );
...
</code>
(the first parameter is $action, ''null'' will cause the form action to be determined automatically)

Secondly, inside the form definition you can use those parameters to set the default values to some of the form's fields
<code php>
...
$mform->addElement('text', 'email', get_string('email'), 'maxlength="100" size="25" ');
$mform->setType('email', PARAM_NOTAGS);
$mform->addRule('email', get_string('missingemail'), 'required', null, 'server');
// Set default value by using a passed parameter
$mform->setDefault('email',$this->_customdata['email']);
...
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. 
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

{{Moodle 2.5}}
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:
<code php>
$mform->setExpanded('foo')
</code>
To close a fieldset on page load, use:
<code php>
$mform->setExpanded('foo', false)
</code>

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== autocomplete ===
{{Moodle 3.1}}
Available since Moodle 3.1

<code php>
$searchareas = \core_search\manager::get_search_areas_list(true);
$areanames = array();
foreach ($searchareas as $areaid => $searcharea) {
$areanames[$areaid] = $searcharea->get_visible_name();
}
$options = array(
'multiple' => true,

'noselectionstring' => get_string('allareas', 'search'),
);
$mform->addElement('autocomplete', 'areaids', get_string('searcharea', 'search'), $areanames, $options);
</code>

The autocomplete element is an advanced form element that supports server-side searching - or simple filtering of a predefined list of options. Some benefits of using this form element are that it handles very large datasets extremely well - it has great accessibility built in - and it gives a good user experience. If you have so much data you need to build pagination into a page - you could probably come up with a better design using this. The simplest way to use it is compatible with the standard 'select' form element. You give it a list of options and some parameters to configure how it behaves. The valid parameters for this simple mode of operation are:
* multiple (boolean - default false) - Allow more than one selected item. The data coming from the form will be an array in this case.

[[image:autocomplete_multiple2.png|center|thumb|alt=autocomplete with multiple option|autocomplete with multiple option.]]

* noselectionstring (string - default <nowiki>''</nowiki>) - The text to display when nothing is selected.
* showsuggestions (boolean - default true) - Do not show the list of suggestions when the user starts typing.
* placeholder (string - default <nowiki>''</nowiki>) - The text to show in the search box when it is empty.
* casesensitive (boolean - default false) - Is the search case sensitive ?
* tags (boolean - default false) - This changes the behaviour so that the user can create new valid entries in the list by typing them and pressing enter.
* ajax (string - default <nowiki>''</nowiki>) - This string is the name of an AMD module that can fetch and format results.
* valuehtmlcallback - For use with the AJAX option, so that it can format the initial value of the form field (available since Moodle 3.5)

More explanation on the 'ajax' option. This should be the name of an AMD module that implements 2 functions:
<code javascript>
/**
* Source of data for Ajax element.
*
* @param {String} selector The selector of the auto complete element.
* @param {String} query The query string.
* @param {Function} callback A callback function receiving an array of results.
* @return {Void}
*/
transport: function(selector, query, callback) ...

/**
* Process the results for auto complete elements.
*
* @param {String} selector The selector of the auto complete element.
* @param {Array} results An array or results.
* @return {Array} New array of results.
*/
processResults: function(selector, results)...

</code>
A good example is here: [https://github.com/moodle/moodle/blob/master/admin/tool/lp/amd/src/frameworks_datasource.js admin/tool/lp/amd/src/frameworks_datasource.js]

The 'valuehtmlcallback' function is needed when an AJAX-supporting form field has an initial value that needs special rendering, similar to how the AJAX code would render it when the user changes it dynamically. For example, if the field contains user ids and its initial value is '1,2' then you want it to use the rendered HTML display for each value (probably a user's name and picture), not just display those numbers. Here is an example, from /search/classes/output/form/search.php:

<code php>
'valuehtmlcallback' => function($value) {
global $DB, $OUTPUT;
$user = $DB->get_record('user', ['id' => (int)$value], '*', IGNORE_MISSING);
if (!$user || !user_can_view_profile($user)) {
return false;
}
$details = user_get_user_details($user);
return $OUTPUT->render_from_template(
'core_search/form-user-selector-suggestion', $details);
}
</code>

The Mustache template used here is the same as the one used by the AJAX code when the field is changed dynamically.

When using the ajax option in an mform with validation etc - it is recommended to sub-class the php class "MoodleQuickForm_autocomplete" so that you can provide a list of name and
values to populate the form element if the form is re-displayed due to a validation error. An example is [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/classes/form/framework_autocomplete.php admin/tool/lp/classes/form/framework_autocomplete.php].

We have provided several useful subclasses of this form element already that are simple to use (course and tags).

<code php>
// Course example.
// Valid options are:
// 'multiple' - boolean multi select
// 'exclude' - array or int, list of course ids to never show
// 'requiredcapabilities' - array of capabilities. Uses ANY to combine them.
// 'limittoenrolled' - boolean Limits to enrolled courses.
// 'includefrontpage' - boolean Enables the frontpage to be selected.
$options = array('multiple' => true, 'includefrontpage' => true);
$mform->addElement('course', 'mappedcourses', get_string('courses'), $options);

// Tags
// Valid options are:
// 'showstandard' - boolean One of the core_tag_tag constants to say which tags to display
// 'component' - string The component name and itemtype define the tag area
// 'itemtype' - string The component name and itemtype define the tag area
$mform->addElement('tags', 'interests', get_string('interestslist'), array('itemtype' => 'user', 'component' => 'core'));
</code>

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

'''BEWARE:''' Unchecked checkboxes return nothing at all (as if they didn't exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. 'Advcheckbox' eliminates this problem.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with some important improvements:

# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

'''Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== editor ===

This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.

<code php>
$mform->addElement('editor', 'fieldname', get_string('labeltext', 'langfile'));
$mform->setType('fieldname', PARAM_RAW);
</code>

NOTE: It won't work properly without the setType() as shown.

If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].

You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:

<code php>
array(
'subdirs'=>0,
'maxbytes'=>0,
'maxfiles'=>0,
'changeformat'=>0,
'context'=>null,
'noclean'=>0,
'trusttext'=>0,
'enable_filemanagement' => true);
</code>

The option 'enable_filemanagement' will display the file management button on true and remove it on false.

To save the data if you don't care about files:
<code php>
$formdata = $mform->get_data();
$text = $formdata->fieldname['text'];
$format = $formdata->fieldname['format'];
</code>

Note: Because the text editor might be "Atto" (depending on user preferences) and Atto has an "autosave" feature - it requires that the combination of $PAGE->url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If there is no requirement to save the file, you can read the file contents directly into a string as follows...

<code php>
$mform->get_file_content('attachment');
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

These elements are now deprecated. Please use the [[#editor|editor]] field type instead.

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===modvisible===
<pre>
$mform->addElement('modvisible', 'visible', get_string('visible'));
</pre>
This is a custom element for selecting a grade visibility in an activity mod update form.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===
{{Moodle 2.3}}
<code php>
$radioarray=array();
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

You can set an 'onchange' attribute when adding or creating the select element:

$form->addElement('select', 'iselTest', 'Test Select:', $arrayOfOptions, array('onchange' => 'javascript:myFunctionToDoSomething();'));

====multi-select====
<pre>
$select = $mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

=====setSelected=====

To set the default selected item in a select element, you can use the 'setSelected' method. The 'setSelected' can either get a value or an array of values.

<pre>
$options = array(
'ff0000' => 'Red',
'00ff00' => 'Green',
'0000ff' => 'Blue'
);
$select = $mform->addElement('select', 'colors', get_string('colors'), $options);
// This will select the colour blue.
$select->setSelected('0000ff');
</pre>

Or for multiple-selection:
<pre>
$skillsarray = array(
'val1' => 'Skill A',
'val2' => 'Skill B',
'val3' => 'Skill C'
);
$mform->addElement('select', 'md_skills', get_string('skills', 'metadata'), $skillsarray);
$mform->getElement('md_skills')->setMultiple(true);
// This will select the skills A and B.
$mform->getElement('md_skills')->setSelected(array('val1', 'val2'));
</pre>

However you probably don't want to do this. Instead you probably want to use setDefault, or set it using the form's setData method.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===selectwithlink===
<pre>
$options = array();
$mform->addElement('selectwithlink', 'scaleid', get_string('scale'), $options, null,
array('link' => $CFG->wwwroot.'/grade/edit/scale/edit.php?courseid='.$COURSE->id, 'label' => get_string('scalescustomcreate')));
</pre>
select type element with options containing link
===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));
</pre>

This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = $mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = $mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', ' ', false);
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<pre>
$this->add_action_buttons();
</pre>

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text input element. (For text labels, use the 'static' element.) Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

====RTL support====
{{Moodle 3.2}}

As of Moodle 3.2, some form elements have been refined to better support right-to-left languages. In RTL, most fields should not have their direction flipped, a URL, a path to a file, a number, ... are always displayed LTR. Input fields and text areas now will best guess whether they should be forced to be displayed in LTR based on the PARAM type associated with it. You can call:
<pre>
$mform->setForceLtr('name', true/false);
</pre>
on some form fields (like 'text') to manually set the value, and for directionality.

====float====
{{Moodle 3.7}}
<pre>
$mform->addElement('float', 'defaultmark', get_string('defaultmark', 'question'), $attributes);
</pre>
Use the float element if you want a text box to get a floating point number. This element automatically supports localised decimal separators. You don't need to use setType with the float element.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

===grading===
<code php>
$mform->addElement('grading', 'advancedgrading', get_string('grade').':', array('gradinginstance' => $gradinginstance));
</code>

Custom element for advanced grading plugins.

When adding the 'grading' element to the form, developer must pass an object of class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be thrown.

===questioncategory===
<code php>
$mform->addElement('questioncategory', 'category', get_string('category', 'question'),
array('contexts'=>$contexts, 'top'=>true, 'currentcat'=>$currentcat, 'nochildrenof'=>$currentcat));
</code>
Creates a drop down element to select a question category.

Options are:
'''contexts''' - (required) context in which question appears
'''currentcat''' - (optional) course category
'''top''' - (optional) if true will put top categories on top
'''nochildrenof''' - (optional) Format categories into an indented list reflecting the tree structure

=== filetypes ===
{{Moodle 3.4}}
Available since Moodle 3.4

<code php>
$mform->addElement('filetypes', 'allowedfiletypes', get_string('allowedfiletypes', 'tool_myplugin'));
</code>

Creates an input element allowing the user to specify file types for the given purpose. The typical scenario is a setting that allows the teacher define a list of allowed file types submitted by students.

The element allows the user to either type the list of filetypes manually, or select the types from the list. Also supported is selecting the whole group of file types - such as "image". The element integrates with the [[Core filetypes]] system so all default types and groups are presented, as well as those [[:en:Working with files#Site administration settings|defined locally by the admin]].

As the list can be types in manually, the form processing code should always normalize it first via the provided utility methods:

<code php>
$formdata = $mform->get_data();
$filetypesutil = new \core_form\filetypes_util();
$allowedfiletypes = $filetypesutil->normalize_file_types($formdata->allowedfiletypes);
</code>

This always returns an array of recognized valid values. The original list can be separated by whitespace, end of lines, commas, colons and semicolons. During the normalization, values are converted to lowercase, empty valies and duplicates are removed. Glob evaluation is not supported.

The normalization should also happen if the previously defined list had been saved to the database and re-read for actual usage. The normalization output value can be directly used as the accepted_types option for the filepicker.

<code php>
$filetypesutil = new \core_form\filetypes_util();
$options['accepted_types'] = $filetypesutil->normalize_file_types($allowedfiletypes);
</code>

By default, user input is validated against the list of known file types and groups. This validation can be disabled via options.

'''Supported options'''

; onlytypes : Allow selection from these file types only; for example ['onlytypes' => ['web_image']].
; allowall : Allow to select 'All file types', defaults to true. Does not apply with onlytypes are set.
; allowunknown : Skip implicit validation against the list of known file types.

Example:

<code php>
$mform->addElement('filetypes', 'doctypes', get_string('doctypes', 'tool_myplugin'), ['onlytypes' => ['document'], 'allowunknown' => true]);
</code>

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');
</pre>

* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems);
</pre>

* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems, null, false);
</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

===Server side and Client side===
In case you use the ''Client side'' validation option, you can mainly check for an empty or not input field. unless you write some ''Client side'' code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.
In case you need a more complex validation checks which relay on Moodle's internal PHP libraries (or other/external PHP libraries) you better use the ''Server side'' validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client's side.

==addHelpButton==

<code php>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</code>

The following parameters are expected:

<code php>
/**
* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in
*/
</code>

# get_string($identifier, $component) // The title of the help page
# get_string("{$identifier}_help", $component) // The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers.
<code php>
$mform->addHelpButton('shuffleanswers', 'shuffleanswers', 'qtype_multichoice');
</code>
and so the language file includes the strings
<code php>
$string['shuffleanswers'] = 'Shuffle the choices?';
$string['shuffleanswers_help'] = 'If enabled,.....';
</code>
You can also add the language string like
<code php>
$string['shuffleanswers_link'] = 'question/shuffleanswers';
</code>
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

<pre>
$mform->addElement('editor', 'desc', get_string('description'));
$mform->setDefault('desc', array('text'=>$defaulttext));
</pre>

Note that when setting the default for an editor element you must use an array to define the default "text" value as shown above.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1')

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq', 'in' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'in' then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control when a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'neq', 42);

The possible choices here are in the dependency manager in lib/form/form.js.
===A tricky case===

You need to take care with disabledIf if you plan to use it with groups of checkboxes.

Let's say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.

To fix ideas:

If the selection in the checkboxes group is:

mycheck_01 == 1
mycheck_02 == 0
mycheck_03 == 0
mycheck_04 == 0
mycheck_05 == 1

the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.

The following code will, apparently, fail:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'neq', '1');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'neq', '1');
</code>

In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element "mycheck_01" and will not apply the corresponding rule.

A working solution for this kind of issue seems to be:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'notchecked');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'notchecked');
</code>
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.

==hideIf==
{{Moodle 3.4}}
For any element or groups of element in a form you can conditionally hide the group or individual element depending on conditions.
This uses the same syntax as disabledIf just with hideIf instead.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==disable_form_change_checker==

By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call

$mform->disable_form_change_checker()

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]
[[Category:Interfaces]]

Running acceptance test

2020-11-05T12:39:31Z

Tim Hunt:

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====
First, you should have a look at [[Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium#Working_combinations_of_OS.2BBrowser.2Bselenium|working combinations of OS+Browser+selenium]].

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/]. Ensure you have the right version of the Chrome driver - see [[#Trouble_shooting| Trouble shooting]]. (Firefox is currently problematic. See [[Actual_Selenium_with_old_Firefox_47.0.1]] if you need to try to make it work.)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)
# At the end of each line it shows you the number of steps that have completed so far.
#* If you are doing a full run, then as of November 2020 there are about 63,000 steps, which took around 25 hours to complete on one test machine (when not using the parallel running feature). Moodle HQ manage complete runs in ~5 hours on a well-optmised set-up, with 3 parallel workers.

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j=<number> or --parallel=<number>''' (required) Number of parallel behat run to initialise
# '''-m=<number> or --maxruns=<number>''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun=<number>''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun=<number>''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a=<name> or --add-core-features-to-theme=<name>''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

You almost always want to limit the number of tests that are run. To run all the tests in one plugin:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin
</code>

To run all the tests in one .feature file:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature
</code>

To run a single scenario:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature:40
</code>

Here, '40' is the line-number of the feature file where the Scenario starts.

=== Parallel runs ===
For running parallel runs, use following command

php admin/tool/behat/cli/run.php

Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

Example: Initialise and run Behat tests for a custom plugin under a custom theme:

php admin/tool/behat/cli/init.php --parallel=3 --add-core-features-to-theme="mytheme"
php admin/tool/behat/cli/run.php --tags="@tool_myplugin" --suite="mytheme"

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" iframe''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with --add-core-features-to-theme={THEME_NAME}, e.g.

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===

If you follow the steps above, Behat will run with Chrome.

You can get it to run with other browsers. The basic idea is to expand the $CFG->behat_profiles array in config.php to list more browsers.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>

[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Run tests directly in Chrome, with no Selenium ===

Historically, the tests would talk to a Selenium server, which would then tell the target browser what to do. More and more, the browsers themselves contain such a server and you can talk to them directly, which is faster and easier. Work was done to get this working with Chrome in MDL-58948, but it still needs some further setup to get it working, which is detailed in the bug ticket, and which I'll copy below:

Replace your current behat config with the abve, the api_url is where you'll talk directly to your Chrome browser.
<code>
$CFG->behat_config = [
'default' => [
'extensions' => [
'DMore\ChromeExtension\Behat\ServiceContainer\ChromeExtension' => [],
'Behat\MinkExtension' => [
'browser_name' => 'chrome',
'base_url' => $CFG->behat_wwwroot,
'goutte' => null,
'selenium2' => null,
'sessions' => [
'javascript' => [
'chrome' => [
'api_url' => 'http://localhost:9222'
]
]
]
]
]
],
];
</code>

Use composer to install two more required libraries:
<code>
composer require --dev dmore/behat-chrome-extension
composer require --dev dmore/chrome-mink-driver
</code>

If you try to run the tests it will tell you that Chrome isn't running, in a second tab run the following to start Chrome (or chromium-browser on Ubuntu)

<code>chrome --disable-gpu --headless --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222</code>

This is running headless so you won't see any windows pop up as the tests run, though it runs in the other mode too.

Behat should now run as before, but faster.

==== Run Chrome locally with Behat and Moodle on a remote server ====
If you have Moodle running on a remote (headless) server, but don't want to install a window manager, you can do the following:

1. Go through all the steps from above

2. Establish an SSH SOCKS5 proxy connection to your server:
<code>ssh -D VARIABLE-PORT-A -N -q -C USER@SERVER</code>
3. Forward the port to connect to the DevTools-API of your browser:
<code>ssh -R VARIABLE-PORT-B:localhost:VARIABLE-PORT-B USER@SERVER -N -q -C</code>
4. Tell your local Chrome to use custom settings:
<code>/path/to/Google\ Chrome [--disable-gpu] --remote-debugging-address=0.0.0.0 --remote-debugging-port=VARIABLE-PORT-B --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A --proxy-bypass-list='<-loopback>'</code>

Or, all in one command:
<code>ssh -D VARIABLE-PORT-A -N -q -C -f USER@SERVER && ssh -R VARIABLE-PORT-B:localhost:VARIABLE-PORT-B USER@SERVER -N -q -C -f && /path/to/Google\ Chrome [--disable-gpu] --remote-debugging-address=0.0.0.0 --remote-debugging-port=VARIABLE-PORT-B --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A --proxy-bypass-list='<-loopback>'</code>

Explanation for the SSH settings:
* VARIABLE-PORT-B & VARIABLE-PORT-A : Choose these as you like. Bear in mind that you will need root rights if the port number is 1023 or lower
* -N: Tells SSH not to open an actual command prompt
* -C: Compress all data passed through the tunnel
* -q: Quiet mode. Causes most warning and diagnostic messages to be suppressed
*-R: Open a tunnel binding to localhost on the remote machine, going to localhost on the local machine
* -f: Fork the process into background

Explanation for the Chrome settings:
* --proxy-bypass-list='<-loopback>' : Tells Chrome to send requests to localhost through the tunnel
* --proxy-server=socks://127.0.0.1:VARIABLE-PORT-A : To use the SOCKS5 tunnel we just set up
* --remote-debugging-port=VARIABLE-PORT-B & --remote-debugging-address=0.0.0.0 : To use the SSH tunnel we just set up

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== Trouble shooting ==

=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===

If you followed all the steps and you receive an unknown weird error probably your browser version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== The tests are failing, and the error message is completely useless ===

For example, it just says "Error writing to database" with no stack trace.

Add -vv command-line option to get very verbose output.

=== Errors during setup (before test are launched) ===
Typical errors are:
* Behat requirement not satisfied: http://127.0.0.1/m/stable_master is not available, ensure you specified correct url and that the server is set up and started.
* Behat is configured but not enabled on this test site.

In order to fix those errors please check that: the behat_dataroot has correct write permissions and that the $CFG->behat* variables are placed before the lib/setup.php include:
require_once(__DIR__ . '/lib/setup.php');

=== Selenium server is not running ===
==== Chrome specific ====

If you are using chrome, you need to ensure that the driver matches the version of the installed chrome browser – which may change on OS updates/upgrades. Moodle or Selenium will not give the appropriate message – see [https://tracker.moodle.org/browse/MDL-67659/ MDL-67659]. One solution is the one suggested in the issue and use Andrew Nicols’ [https://github.com/andrewnicols/chromedriver-wrapper/ Chromedriver Wrapper] which will ensure you have the appropriate driver before running the tests.

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

== See also ==
* [[Acceptance testing for the mobile app]]

[[Category:Quality Assurance]][[Category:Behat]]

Developer meeting October 2020

2020-10-13T11:52:16Z

Tim Hunt:

[[Developer meetings]] > October 2020 meeting

{| class="nicetable"
|-
| Date
| Tuesday 13 October 2020 at 07:00 UTC ([https://www.timeanddate.com/worldclock/fixedtime.html?msg=Moodle+developer+meeting&iso=20201013T07&p1=1440&ah=1 Check this time in your location])
|-
| Meeting recording
| https://moodle.org/mod/bigbluebuttonbn/view.php?id=8596
|-
| Discussion
| https://moodle.org/mod/forum/discuss.php?d=410039
|}

== Agenda ==

# Latest #moodledev news - [https://moodle.org/user/view.php?id=2356736&course=5 Sander Bangma]
#* [[:File:Community_Dev_Meeting_-_LMS_Update_-_Oct_2020a.pdf|Sander's presentation slides]]
# The Question bank: how it works, the history of how it got there; the problems that causes; and what we might do in future - special guest [https://moodle.org/user/view.php?id=93821&course=5 Tim Hunt], The Open University, UK
#* [[:File:Moodle question bank dev meeting.pdf|Tim's presentation slides]]
#* To be kept in the loop or to depose needs, offer funds or other contributions please make yourself heard here: [https://forms.gle/ug5kUo342ubJRGZE8 https://forms.gle/ug5kUo342ubJRGZE8]
#* [https://moodle.org/mod/forum/discuss.php?d=412117 Quiz forum discussion about the proposed changes].

----

If there is any topic that you would like to present or discuss at a developer meeting, please contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

Developer meeting October 2020

2020-08-25T12:39:06Z

Tim Hunt:

Availability conditions

2020-08-25T08:05:10Z

Tim Hunt: /* yui (folder) */

{{Moodle 2.9}}

== Introduction ==

Availability conditions allow teachers to restrict an activity or section so that only certain users can access it. These are accessed via the [[Availability API]].

Some of the conditions included in standard Moodle are:

* Date (users can only access activity after specified date)
* Grade (users can only access activity if they have a certain grade in another activity)

== History ==

Availability condition plugins were introduced with Moodle 2.7. In previous versions, the older conditional availability API did not support plugins and was limited to the predefined conditions.

== Example ==

A relatively simple example is the grouping condition which can be found in /availability/condition/grouping. This is the best one to look at, or base your new code on, when starting to implement a new condition.

To see this condition in action:

* Ensure <tt>enableavailability</tt> option is turned on in the Admin -> Advanced features page.
* Go to a course and edit any section.
* Expand the '''Restrict access''' heading.
* Click the '''Add restriction''' button.
* Click '''Grouping'''.

== File structure ==

All files for an availability condition plugin go within /availability/condition/name, where 'name' is the name of the condition plugin. (The examples below assume this folder, with the plugin called availability_name.)

=== version.php ===

Standard [[version.php]] for the component.

=== lang/en/availability_name.php ===

Language strings for the plugin. Required strings:

* '''pluginname''' - name of plugin.
* '''title''' - text of button for adding this type of plugin.
* '''description''' - explanatory text that goes alongside the button in the 'add restriction' dialog.

Example:

<code php>
$string['description'] = 'Silly example plugin that just has a checkbox for whether to allow access';
$string['pluginname'] = 'Restriction by silly checkbox';
$string['title'] = 'Test plugin';
</code>

You will usually need to add your own strings for two main purposes:

* Creating suitable form controls for users who are editing the activity settings.
* Displaying information about the condition.

=== classes/condition.php ===

This PHP class implements the back-end of the condition; in other words, this class contains the code which decides whether a user is allowed to access an activity that uses this condition, or not.

Here's an outline of the code (with standard PHPdoc comments omitted to save space) for a simple example in which there is a boolean value that controls whether access is allowed or not.

<code php>
// You must use the right namespace (matching your plugin component name).
namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class condition extends \core_availability\condition {
// Any data associated with the condition can be stored in member
// variables. Here's an example variable:
protected $allow;

public function __construct($structure) {
// Retrieve any necessary data from the $structure here. The
// structure is extracted from JSON data stored in the database
// as part of the tree structure of conditions relating to an
// activity or section.
// For example, you could obtain the 'allow' value:
$this->allow = $structure->allow;

// It is also a good idea to check for invalid values here and
// throw a coding_exception if the structure is wrong.
}

public function save() {
// Save back the data into a plain array similar to $structure above.
return (object)array('type' => 'name', 'allow' => $this->allow);
}

public function is_available($not,
\core_availability\info $info, $grabthelot, $userid) {
// This function needs to check whether the condition is true
// or not for the user specified in $userid.

// The value $not should be used to negate the condition. Other
// parameters provide data which can be used when evaluating the
// condition.

// For this trivial example, we will just use $allow to decide
// whether it is allowed or not. In a real condition you would
// do some calculation depending on the specified user.
$allow = $this->allow;
if ($not) {
$allow = !$allow;
}
return $allow;
}

public function get_description($full, $not, \core_availability\info $info) {
// This function just returns the information that shows about
// the condition on editing screens. Usually it is similar to
// the information shown if the user doesn't meet the
// condition (it does not depend on the current user).
$allow = $not ? !$this->allow : $this->allow;
return $allow ? 'Users are allowed' : 'Users not allowed';
}

protected function get_debug_string() {
// This function is only normally used for unit testing and
// stuff like that. Just make a short string representation
// of the values of the condition, suitable for developers.
return $this->allow ? 'YES' : 'NO';
}
}
</code>

There are other functions you might also want to implement. For example, if your condition should apply to lists of users (in general, conditions which are 'permanent' such as group conditions apply to lists, whereas those which are 'temporary' such as date or grade conditions do not) then you should also implement is_applied_to_user_lists and filter_user_list functions. To see the full list, look at the PHPdoc for the condition and tree_node classes inside availability/classes.

=== classes/frontend.php ===

You will also need to write a frontend.php class which defines the behaviour of your plugin within the editing form (when a teacher is editing the activity settings).

The class is required, but all the functions are theoretically optional; you can leave them out if you don't need any special behaviour for that function. In practice it's likely you will need at least one of them.

<code php>
namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class frontend extends \core_availability\frontend {

protected function get_javascript_strings() {
// You can return a list of names within your language file and the
// system will include them here. (Should you need strings from another
// language file, you can also call $PAGE->requires->strings_for_js
// manually from here.)
return array();
}

protected function get_javascript_init_params($course, \cm_info $cm = null,
\section_info $section = null) {
// If you want, you can add some parameters here which will be
// passed into your JavaScript init method. If you don't include
// this function, there will be no parameters.
return array('frog');
}

protected function allow_add($course, \cm_info $cm = null,
\section_info $section = null) {
// This function lets you control whether the 'add' button for your
// plugin appears. For example, the grouping plugin does not appear
// if there are no groupings on the course. This helps to simplify
// the user interface. If you don't include this function, it will
// appear.
return true;
}
}
</code>

=== yui (folder) ===

These conditions use YUI Shifter to generate JavaScript code. Although JavaScript standards in Moodle have moved on, the core avaiability system is implemented in YUI, so for now, the plugins need to use YUI too. (Please, someone, do MDL-69566!)

Unfortunately that does mean you need to create a few layers of boilerplate folders. If you are unfamiliar with Shifter, here is a quick summary:

# Install it according to the instructions here: [[YUI/Shifter]]
# In a command prompt, change to the directory that contains your plugin and run: <tt>shifter --watch</tt>
# Create or modify the files described below.

Shifter will then automatically build your files whenever you change them. You have to remember to run it whenever you make a change. (If you accidentally make a change while it's not running, run it and then make another change.)

=== yui/src/form/meta/form.json ===

Metadata for Shifter relating to the YUI module that contains the JavaScript for your code. You can edit this file to add any additional required YUI modules.

<code javascript>
{
"moodle-availability_name-form": {
"requires": [
"base",
"node",
"event",
"moodle-core_availability-form"
]
}
}
</code>

=== yui/src/form/build.json ===

Metadata for Shifter about how to build this module. You will probably not need to change this file.

<code javascript>
{
"name": "moodle-availability_name-form",
"builds": {
"moodle-availability_name-form": {
"jsfiles": [
"form.js"
]
}
}
}
</code>

=== yui/src/form/js/form.js ===

This is the actual JavaScript code for your plugin. It should follow the below format in order to integrate with the core JavaScript. (Of course, you can add extra functions as needed.)

<code javascript>
M.availability_name = M.availability_name || {};

M.availability_name.form = Y.Object(M.core_availability.plugin);

M.availability_name.form.initInner = function(param) {
// The 'param' variable is the parameter passed through from PHP (you
// can have more than one if required).

// Using the PHP code above it'll show 'The param was: frog'.
console.log('The param was: ' + param);
};

M.availability_name.form.getNode = function(json) {
// This function does the main work. It gets called after the user
// chooses to add an availability restriction of this type. You have
// to return a YUI node representing the HTML for the plugin controls.

// Example controls contain only one tickbox.
var strings = M.str.availability_name;
var html = '<label>' + strings.title + ' <input type="checkbox"/></label>';
var node = Y.Node.create('' + html + '');

// Set initial values based on the value from the JSON data in Moodle
// database. This will have values undefined if creating a new one.
if (json.allow) {
node.one('input').set('checked', true);
}

// Add event handlers (first time only). You can do this any way you
// like, but this pattern is used by the existing code.
if (!M.availability_name.form.addedEvents) {
M.availability_name.form.addedEvents = true;
var root = Y.one('#fitem_id_availabilityconditionsjson');
root.delegate('click', function() {
// The key point is this update call. This call will update
// the JSON data in the hidden field in the form, so that it
// includes the new value of the checkbox.
M.core_availability.form.update();
}, '.availability_name input');
}

return node;
};

M.availability_name.form.fillValue = function(value, node) {
// This function gets passed the node (from above) and a value
// object. Within that object, it must set up the correct values
// to use within the JSON data in the form. Should be compatible
// with the structure used in the __construct and save functions
// within condition.php.
var checkbox = node.one('input');
value.allow = checkbox.get('checked') ? true : false;
};

M.availability_name.form.fillErrors = function(errors, node) {
// If the user has selected something invalid, this optional
// function can be included to report an error in the form. The
// error will show immediately as a 'Please set' tag, and if the
// user saves the form with an error still in place, they'll see
// the actual error text.

// In this example an error is not possible...
if (false) {
// ...but this is how you would add one if required. This is
// passing your component name (availability_name) and the
// name of a string within your lang file (error_message)
// which will be shown if they submit the form.
errors.push('availability_name:error_message');
}
};
</code>

=== tests/condition_test.php (optional) ===

Normally you would write a unit test for the condition inside this file. See existing conditions for examples.

=== tests/behat/availability_name.feature (optional) ===

Normally you would write a Behat test for the condition in this file. See existing conditions for examples.

=== Other files (optional) ===

You can also include other files; standard Moodle files such as styles.css, and arbitrary PHP and JavaScript files as necessary.

== See also ==

* [[Conditional activities API]]

Availability conditions

2020-08-25T07:45:04Z

Tim Hunt: Undo revision 57792 by Tim Hunt (talk)

{{Moodle 2.9}}

== Introduction ==

Availability conditions allow teachers to restrict an activity or section so that only certain users can access it. These are accessed via the [[Availability API]].

Some of the conditions included in standard Moodle are:

* Date (users can only access activity after specified date)
* Grade (users can only access activity if they have a certain grade in another activity)

== History ==

Availability condition plugins were introduced with Moodle 2.7. In previous versions, the older conditional availability API did not support plugins and was limited to the predefined conditions.

== Example ==

A relatively simple example is the grouping condition which can be found in /availability/condition/grouping. This is the best one to look at, or base your new code on, when starting to implement a new condition.

To see this condition in action:

* Ensure <tt>enableavailability</tt> option is turned on in the Admin -> Advanced features page.
* Go to a course and edit any section.
* Expand the '''Restrict access''' heading.
* Click the '''Add restriction''' button.
* Click '''Grouping'''.

== File structure ==

All files for an availability condition plugin go within /availability/condition/name, where 'name' is the name of the condition plugin. (The examples below assume this folder, with the plugin called availability_name.)

=== version.php ===

Standard [[version.php]] for the component.

=== lang/en/availability_name.php ===

Language strings for the plugin. Required strings:

* '''pluginname''' - name of plugin.
* '''title''' - text of button for adding this type of plugin.
* '''description''' - explanatory text that goes alongside the button in the 'add restriction' dialog.

Example:

<code php>
$string['description'] = 'Silly example plugin that just has a checkbox for whether to allow access';
$string['pluginname'] = 'Restriction by silly checkbox';
$string['title'] = 'Test plugin';
</code>

You will usually need to add your own strings for two main purposes:

* Creating suitable form controls for users who are editing the activity settings.
* Displaying information about the condition.

=== classes/condition.php ===

This PHP class implements the back-end of the condition; in other words, this class contains the code which decides whether a user is allowed to access an activity that uses this condition, or not.

Here's an outline of the code (with standard PHPdoc comments omitted to save space) for a simple example in which there is a boolean value that controls whether access is allowed or not.

<code php>
// You must use the right namespace (matching your plugin component name).
namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class condition extends \core_availability\condition {
// Any data associated with the condition can be stored in member
// variables. Here's an example variable:
protected $allow;

public function __construct($structure) {
// Retrieve any necessary data from the $structure here. The
// structure is extracted from JSON data stored in the database
// as part of the tree structure of conditions relating to an
// activity or section.
// For example, you could obtain the 'allow' value:
$this->allow = $structure->allow;

// It is also a good idea to check for invalid values here and
// throw a coding_exception if the structure is wrong.
}

public function save() {
// Save back the data into a plain array similar to $structure above.
return (object)array('type' => 'name', 'allow' => $this->allow);
}

public function is_available($not,
\core_availability\info $info, $grabthelot, $userid) {
// This function needs to check whether the condition is true
// or not for the user specified in $userid.

// The value $not should be used to negate the condition. Other
// parameters provide data which can be used when evaluating the
// condition.

// For this trivial example, we will just use $allow to decide
// whether it is allowed or not. In a real condition you would
// do some calculation depending on the specified user.
$allow = $this->allow;
if ($not) {
$allow = !$allow;
}
return $allow;
}

public function get_description($full, $not, \core_availability\info $info) {
// This function just returns the information that shows about
// the condition on editing screens. Usually it is similar to
// the information shown if the user doesn't meet the
// condition (it does not depend on the current user).
$allow = $not ? !$this->allow : $this->allow;
return $allow ? 'Users are allowed' : 'Users not allowed';
}

protected function get_debug_string() {
// This function is only normally used for unit testing and
// stuff like that. Just make a short string representation
// of the values of the condition, suitable for developers.
return $this->allow ? 'YES' : 'NO';
}
}
</code>

There are other functions you might also want to implement. For example, if your condition should apply to lists of users (in general, conditions which are 'permanent' such as group conditions apply to lists, whereas those which are 'temporary' such as date or grade conditions do not) then you should also implement is_applied_to_user_lists and filter_user_list functions. To see the full list, look at the PHPdoc for the condition and tree_node classes inside availability/classes.

=== classes/frontend.php ===

You will also need to write a frontend.php class which defines the behaviour of your plugin within the editing form (when a teacher is editing the activity settings).

The class is required, but all the functions are theoretically optional; you can leave them out if you don't need any special behaviour for that function. In practice it's likely you will need at least one of them.

<code php>
namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class frontend extends \core_availability\frontend {

protected function get_javascript_strings() {
// You can return a list of names within your language file and the
// system will include them here. (Should you need strings from another
// language file, you can also call $PAGE->requires->strings_for_js
// manually from here.)
return array();
}

protected function get_javascript_init_params($course, \cm_info $cm = null,
\section_info $section = null) {
// If you want, you can add some parameters here which will be
// passed into your JavaScript init method. If you don't include
// this function, there will be no parameters.
return array('frog');
}

protected function allow_add($course, \cm_info $cm = null,
\section_info $section = null) {
// This function lets you control whether the 'add' button for your
// plugin appears. For example, the grouping plugin does not appear
// if there are no groupings on the course. This helps to simplify
// the user interface. If you don't include this function, it will
// appear.
return true;
}
}
</code>

=== yui (folder) ===

These conditions use YUI Shifter to generate JavaScript code. Unfortunately that does mean you need to create a few layers of boilerplate folders.

If you are unfamiliar with Shifter, here is a quick summary:

# Install it according to the instructions here: [[YUI/Shifter]]
# In a command prompt, change to the directory that contains your plugin and run: <tt>shifter --watch</tt>
# Create or modify the files described below.

Shifter will then automatically build your files whenever you change them. You have to remember to run it whenever you make a change. (If you accidentally make a change while it's not running, run it and then make another change.)

=== yui/src/form/meta/form.json ===

Metadata for Shifter relating to the YUI module that contains the JavaScript for your code. You can edit this file to add any additional required YUI modules.

<code javascript>
{
"moodle-availability_name-form": {
"requires": [
"base",
"node",
"event",
"moodle-core_availability-form"
]
}
}
</code>

=== yui/src/form/build.json ===

Metadata for Shifter about how to build this module. You will probably not need to change this file.

<code javascript>
{
"name": "moodle-availability_name-form",
"builds": {
"moodle-availability_name-form": {
"jsfiles": [
"form.js"
]
}
}
}
</code>

=== yui/src/form/js/form.js ===

This is the actual JavaScript code for your plugin. It should follow the below format in order to integrate with the core JavaScript. (Of course, you can add extra functions as needed.)

<code javascript>
M.availability_name = M.availability_name || {};

M.availability_name.form = Y.Object(M.core_availability.plugin);

M.availability_name.form.initInner = function(param) {
// The 'param' variable is the parameter passed through from PHP (you
// can have more than one if required).

// Using the PHP code above it'll show 'The param was: frog'.
console.log('The param was: ' + param);
};

M.availability_name.form.getNode = function(json) {
// This function does the main work. It gets called after the user
// chooses to add an availability restriction of this type. You have
// to return a YUI node representing the HTML for the plugin controls.

// Example controls contain only one tickbox.
var strings = M.str.availability_name;
var html = '<label>' + strings.title + ' <input type="checkbox"/></label>';
var node = Y.Node.create('' + html + '');

// Set initial values based on the value from the JSON data in Moodle
// database. This will have values undefined if creating a new one.
if (json.allow) {
node.one('input').set('checked', true);
}

// Add event handlers (first time only). You can do this any way you
// like, but this pattern is used by the existing code.
if (!M.availability_name.form.addedEvents) {
M.availability_name.form.addedEvents = true;
var root = Y.one('#fitem_id_availabilityconditionsjson');
root.delegate('click', function() {
// The key point is this update call. This call will update
// the JSON data in the hidden field in the form, so that it
// includes the new value of the checkbox.
M.core_availability.form.update();
}, '.availability_name input');
}

return node;
};

M.availability_name.form.fillValue = function(value, node) {
// This function gets passed the node (from above) and a value
// object. Within that object, it must set up the correct values
// to use within the JSON data in the form. Should be compatible
// with the structure used in the __construct and save functions
// within condition.php.
var checkbox = node.one('input');
value.allow = checkbox.get('checked') ? true : false;
};

M.availability_name.form.fillErrors = function(errors, node) {
// If the user has selected something invalid, this optional
// function can be included to report an error in the form. The
// error will show immediately as a 'Please set' tag, and if the
// user saves the form with an error still in place, they'll see
// the actual error text.

// In this example an error is not possible...
if (false) {
// ...but this is how you would add one if required. This is
// passing your component name (availability_name) and the
// name of a string within your lang file (error_message)
// which will be shown if they submit the form.
errors.push('availability_name:error_message');
}
};
</code>

=== tests/condition_test.php (optional) ===

Normally you would write a unit test for the condition inside this file. See existing conditions for examples.

=== tests/behat/availability_name.feature (optional) ===

Normally you would write a Behat test for the condition in this file. See existing conditions for examples.

=== Other files (optional) ===

You can also include other files; standard Moodle files such as styles.css, and arbitrary PHP and JavaScript files as necessary.

== See also ==

* [[Conditional activities API]]

Availability conditions

2020-08-24T09:50:56Z

Tim Hunt: /* yui (folder) */

{{Moodle 2.9}}

== Introduction ==

Availability conditions allow teachers to restrict an activity or section so that only certain users can access it. These are accessed via the [[Availability API]].

Some of the conditions included in standard Moodle are:

* Date (users can only access activity after specified date)
* Grade (users can only access activity if they have a certain grade in another activity)

== History ==

Availability condition plugins were introduced with Moodle 2.7. In previous versions, the older conditional availability API did not support plugins and was limited to the predefined conditions.

== Example ==

A relatively simple example is the grouping condition which can be found in /availability/condition/grouping. This is the best one to look at, or base your new code on, when starting to implement a new condition.

To see this condition in action:

* Ensure <tt>enableavailability</tt> option is turned on in the Admin -> Advanced features page.
* Go to a course and edit any section.
* Expand the '''Restrict access''' heading.
* Click the '''Add restriction''' button.
* Click '''Grouping'''.

== File structure ==

All files for an availability condition plugin go within /availability/condition/name, where 'name' is the name of the condition plugin. (The examples below assume this folder, with the plugin called availability_name.)

=== version.php ===

Standard [[version.php]] for the component.

=== lang/en/availability_name.php ===

Language strings for the plugin. Required strings:

* '''pluginname''' - name of plugin.
* '''title''' - text of button for adding this type of plugin.
* '''description''' - explanatory text that goes alongside the button in the 'add restriction' dialog.

Example:

<code php>
$string['description'] = 'Silly example plugin that just has a checkbox for whether to allow access';
$string['pluginname'] = 'Restriction by silly checkbox';
$string['title'] = 'Test plugin';
</code>

You will usually need to add your own strings for two main purposes:

* Creating suitable form controls for users who are editing the activity settings.
* Displaying information about the condition.

=== classes/condition.php ===

This PHP class implements the back-end of the condition; in other words, this class contains the code which decides whether a user is allowed to access an activity that uses this condition, or not.

Here's an outline of the code (with standard PHPdoc comments omitted to save space) for a simple example in which there is a boolean value that controls whether access is allowed or not.

<code php>
// You must use the right namespace (matching your plugin component name).
namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class condition extends \core_availability\condition {
// Any data associated with the condition can be stored in member
// variables. Here's an example variable:
protected $allow;

public function __construct($structure) {
// Retrieve any necessary data from the $structure here. The
// structure is extracted from JSON data stored in the database
// as part of the tree structure of conditions relating to an
// activity or section.
// For example, you could obtain the 'allow' value:
$this->allow = $structure->allow;

// It is also a good idea to check for invalid values here and
// throw a coding_exception if the structure is wrong.
}

public function save() {
// Save back the data into a plain array similar to $structure above.
return (object)array('type' => 'name', 'allow' => $this->allow);
}

public function is_available($not,
\core_availability\info $info, $grabthelot, $userid) {
// This function needs to check whether the condition is true
// or not for the user specified in $userid.

// The value $not should be used to negate the condition. Other
// parameters provide data which can be used when evaluating the
// condition.

// For this trivial example, we will just use $allow to decide
// whether it is allowed or not. In a real condition you would
// do some calculation depending on the specified user.
$allow = $this->allow;
if ($not) {
$allow = !$allow;
}
return $allow;
}

public function get_description($full, $not, \core_availability\info $info) {
// This function just returns the information that shows about
// the condition on editing screens. Usually it is similar to
// the information shown if the user doesn't meet the
// condition (it does not depend on the current user).
$allow = $not ? !$this->allow : $this->allow;
return $allow ? 'Users are allowed' : 'Users not allowed';
}

protected function get_debug_string() {
// This function is only normally used for unit testing and
// stuff like that. Just make a short string representation
// of the values of the condition, suitable for developers.
return $this->allow ? 'YES' : 'NO';
}
}
</code>

There are other functions you might also want to implement. For example, if your condition should apply to lists of users (in general, conditions which are 'permanent' such as group conditions apply to lists, whereas those which are 'temporary' such as date or grade conditions do not) then you should also implement is_applied_to_user_lists and filter_user_list functions. To see the full list, look at the PHPdoc for the condition and tree_node classes inside availability/classes.

=== classes/frontend.php ===

You will also need to write a frontend.php class which defines the behaviour of your plugin within the editing form (when a teacher is editing the activity settings).

The class is required, but all the functions are theoretically optional; you can leave them out if you don't need any special behaviour for that function. In practice it's likely you will need at least one of them.

<code php>
namespace availability_name;

defined('MOODLE_INTERNAL') || die();

class frontend extends \core_availability\frontend {

protected function get_javascript_strings() {
// You can return a list of names within your language file and the
// system will include them here. (Should you need strings from another
// language file, you can also call $PAGE->requires->strings_for_js
// manually from here.)
return array();
}

protected function get_javascript_init_params($course, \cm_info $cm = null,
\section_info $section = null) {
// If you want, you can add some parameters here which will be
// passed into your JavaScript init method. If you don't include
// this function, there will be no parameters.
return array('frog');
}

protected function allow_add($course, \cm_info $cm = null,
\section_info $section = null) {
// This function lets you control whether the 'add' button for your
// plugin appears. For example, the grouping plugin does not appear
// if there are no groupings on the course. This helps to simplify
// the user interface. If you don't include this function, it will
// appear.
return true;
}
}
</code>

=== amd (folder) ===

These conditions use JavaScript code.

TODO, update the below to be relevant to AMD, not YUI.

If you are unfamiliar with Shifter, here is a quick summary:

# Install it according to the instructions here: [[YUI/Shifter]]
# In a command prompt, change to the directory that contains your plugin and run: <tt>shifter --watch</tt>
# Create or modify the files described below.

Shifter will then automatically build your files whenever you change them. You have to remember to run it whenever you make a change. (If you accidentally make a change while it's not running, run it and then make another change.)

=== yui/src/form/meta/form.json ===

Metadata for Shifter relating to the YUI module that contains the JavaScript for your code. You can edit this file to add any additional required YUI modules.

<code javascript>
{
"moodle-availability_name-form": {
"requires": [
"base",
"node",
"event",
"moodle-core_availability-form"
]
}
}
</code>

=== yui/src/form/build.json ===

Metadata for Shifter about how to build this module. You will probably not need to change this file.

<code javascript>
{
"name": "moodle-availability_name-form",
"builds": {
"moodle-availability_name-form": {
"jsfiles": [
"form.js"
]
}
}
}
</code>

=== yui/src/form/js/form.js ===

This is the actual JavaScript code for your plugin. It should follow the below format in order to integrate with the core JavaScript. (Of course, you can add extra functions as needed.)

<code javascript>
M.availability_name = M.availability_name || {};

M.availability_name.form = Y.Object(M.core_availability.plugin);

M.availability_name.form.initInner = function(param) {
// The 'param' variable is the parameter passed through from PHP (you
// can have more than one if required).

// Using the PHP code above it'll show 'The param was: frog'.
console.log('The param was: ' + param);
};

M.availability_name.form.getNode = function(json) {
// This function does the main work. It gets called after the user
// chooses to add an availability restriction of this type. You have
// to return a YUI node representing the HTML for the plugin controls.

// Example controls contain only one tickbox.
var strings = M.str.availability_name;
var html = '<label>' + strings.title + ' <input type="checkbox"/></label>';
var node = Y.Node.create('' + html + '');

// Set initial values based on the value from the JSON data in Moodle
// database. This will have values undefined if creating a new one.
if (json.allow) {
node.one('input').set('checked', true);
}

// Add event handlers (first time only). You can do this any way you
// like, but this pattern is used by the existing code.
if (!M.availability_name.form.addedEvents) {
M.availability_name.form.addedEvents = true;
var root = Y.one('#fitem_id_availabilityconditionsjson');
root.delegate('click', function() {
// The key point is this update call. This call will update
// the JSON data in the hidden field in the form, so that it
// includes the new value of the checkbox.
M.core_availability.form.update();
}, '.availability_name input');
}

return node;
};

M.availability_name.form.fillValue = function(value, node) {
// This function gets passed the node (from above) and a value
// object. Within that object, it must set up the correct values
// to use within the JSON data in the form. Should be compatible
// with the structure used in the __construct and save functions
// within condition.php.
var checkbox = node.one('input');
value.allow = checkbox.get('checked') ? true : false;
};

M.availability_name.form.fillErrors = function(errors, node) {
// If the user has selected something invalid, this optional
// function can be included to report an error in the form. The
// error will show immediately as a 'Please set' tag, and if the
// user saves the form with an error still in place, they'll see
// the actual error text.

// In this example an error is not possible...
if (false) {
// ...but this is how you would add one if required. This is
// passing your component name (availability_name) and the
// name of a string within your lang file (error_message)
// which will be shown if they submit the form.
errors.push('availability_name:error_message');
}
};
</code>

=== tests/condition_test.php (optional) ===

Normally you would write a unit test for the condition inside this file. See existing conditions for examples.

=== tests/behat/availability_name.feature (optional) ===

Normally you would write a Behat test for the condition in this file. See existing conditions for examples.

=== Other files (optional) ===

You can also include other files; standard Moodle files such as styles.css, and arbitrary PHP and JavaScript files as necessary.

== See also ==

* [[Conditional activities API]]

Writing acceptance tests

2020-08-19T09:19:17Z

Tim Hunt: /* Custom selectors (... in the "..." "...") */

== 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.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

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

== Create your 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:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
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:
<code behat>
@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
</code>
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:
<code behat>
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 |
</code>
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.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** icon - for searching an icon by its title
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** list_item - for searching a list item which contains the specified text
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== 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:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
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
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and 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 [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

==== Writing your own steps ====

Sometimes, you will need to set up data that is specific to your plugin, or perform steps that are specific to your plugin's UI. In this case it may be necessary to [[Writing_new_acceptance_test_step_definitions|write new step definitions]], but the short version is that you define new steps as PHP methods with a special annotation inside a class called <tt>behat_plugintype_plugingname</tt> inside tests/behat/behat_plugintype_plugingname.php in your plugin.

As well as creating completely new steps, you can also extend some of the standard steps:

===== Custom selectors (<tt>... in the "..." "..."</tt>) =====

There are a load of different steps which can refer to specific items on-screen, for example

And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"

Here, 'button' and 'dialogue' are examples of selectors, and 'Submit all and finish' and 'Confirmation' are the locators which say which button or dialogue it is. When the test runs, this gets converted to an XPath expression, which is what the Behat system acutally uses to locate the right element on the page.

From Moodle 3.8 onwards, you can define new types of selector (for example <tt>core_message > Message</tt>) by implementing functions like <tt>behat_component_named_selector</tt> in your plugin's <tt>behat_plugintype_plugingname</tt> class. The detailed instructions for how to do this are in [https://github.com/moodle/moodle/blob/33da028c27607354981cd8e62ecabb7b973c6637/lib/behat/behat_base.php#L1111 the PHPdoc comments on the base class].

The reasons you might want to do this are:
* It makes your tests easier to read, which makes it easier to be sure that the test is testing the right thing, and being able to read the tests helps people understand your features.
* If the HTML structure you output changes, then you only need to update the selector definition in one place.

===== Custom navigation targets (<tt>And I am on the "..." "..." page</tt>) =====

From Moodle 3.8 onwards,there are two related steps:

Given I am on the "Quiz 1" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page

To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you you needs to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about hwo this works are given in [https://github.com/moodle/moodle/blob/a0fc902eb184cd4097c8ab453ddc57964cd2dbd4/lib/behat/behat_base.php#L1093 the PHPdoc comments on the base class].

There are two reasons why it is good to use these steps:
* You are trying to test that your feature works, not Moodle navigation. In the pase we have had many occasions when Moodle navigation changed, and lots of tests failed and had to be fixed. It is better for your tests to start on your feature. (Except, perhpas, it might be appropriate to have one test for the expected method for users to navigate to your feature.)
* It is much faster because you load fewer irrelevant pages, and in particular the normal loggi step leaves you on the Dashboard page, which is '''very''' slow to load.

===== Custom entity generators (<tt>And the following "..." exist:</tt>) =====

From Moodle 3.8 onwards, it is possible to extend the ''Given the following "entites" exist'' step to support your plugin's data generators. This avoids having to write new whole
new behat step definitions for your plugin, and allows you to re-use data generators between PHPUnit and Behat tests.

Full documentation of this process and all available options can be found in the [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/lib/behat/classes/behat_generator_base.php#L33 PHPDoc for behat_generator_base]. A core example of this can be found in [https://github.com/moodle/moodle/tree/master/mod/quiz/tests/generator /mod/quiz/tests/generator] and [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/mod/quiz/tests/behat/quiz_reset.feature#L51 quiz_reset.feature]. What follows is a simple example.

To begin, you need a [[Writing_PHPUnit_tests#Generators|generator]] in /''your''/''plugin''/tests/generator/lib.php. If you are generating a type of entity called "thing", your generator will need a method called create_thing, which accepts an object:

<code php>
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</code>

Next, you will need to define your behat generator in /''your''/''plugin''/tests/generator/behat_''your_plugin''_generator.php, with the method get_createable_entitites():

<code php>
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</code>

The 'datagenerator' value refers to the method in the generator class that we are calling, in this case ''create_thing()''. The outer array key is the entity name we will use in the behat step, in this case ''Given the following "local_myplugin > things" exist''.

Now, in your behat test, you can have a step like this, which will generate 2 ''things'', the first with the name "thing1" and the second with the name "thing2".

<code gherkin>
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

Note that this also implies that the Given, When and Then keywords should be used only once per scenario.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Writing acceptance tests

2020-08-19T09:16:23Z

Tim Hunt: /* Custom navigation targets (And I am on the "..." "..." page) */

== 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.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

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

== Create your 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:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
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:
<code behat>
@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
</code>
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:
<code behat>
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 |
</code>
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.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** icon - for searching an icon by its title
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** list_item - for searching a list item which contains the specified text
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== 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:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
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
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and 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 [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

==== Writing your own steps ====

Sometimes, you will need to set up data that is specific to your plugin, or perform steps that are specific to your plugin's UI. In this case it may be necessary to [[Writing_new_acceptance_test_step_definitions|write new step definitions]], but the short version is that you define new steps as PHP methods with a special annotation inside a class called <tt>behat_plugintype_plugingname</tt> inside tests/behat/behat_plugintype_plugingname.php in your plugin.

As well as creating completely new steps, you can also extend some of the standard steps:

===== Custom selectors (<tt>... in the "..." "..."</tt>) =====

There are a load of different steps which can refer to specific items on-screen, for example

And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"</code>

Here, 'button' and 'dialogue' are examples of selectors, and 'Submit all and finish' and 'Confirmation' are the locators which say which button or dialogue it is.

From Moodle 3.8 onwards, you can define new types of selector (for example <tt>core_message > Message</tt>) by implementing functions like <tt>behat_component_named_selector</tt> in your plugin's <tt>behat_plugintype_plugingname</tt> class.

The detailed instructions for how to do this are in [https://github.com/moodle/moodle/blob/33da028c27607354981cd8e62ecabb7b973c6637/lib/behat/behat_base.php#L1111 the PHPdoc comments on the base class].

===== Custom navigation targets (<tt>And I am on the "..." "..." page</tt>) =====

From Moodle 3.8 onwards,there are two related steps:

Given I am on the "Quiz 1" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page

To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you you needs to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about hwo this works are given in [https://github.com/moodle/moodle/blob/a0fc902eb184cd4097c8ab453ddc57964cd2dbd4/lib/behat/behat_base.php#L1093 the PHPdoc comments on the base class].

There are two reasons why it is good to use these steps:
* You are trying to test that your feature works, not Moodle navigation. In the pase we have had many occasions when Moodle navigation changed, and lots of tests failed and had to be fixed. It is better for your tests to start on your feature. (Except, perhpas, it might be appropriate to have one test for the expected method for users to navigate to your feature.)
* It is much faster because you load fewer irrelevant pages, and in particular the normal loggi step leaves you on the Dashboard page, which is '''very''' slow to load.

===== Custom entity generators (<tt>And the following "..." exist:</tt>) =====

From Moodle 3.8 onwards, it is possible to extend the ''Given the following "entites" exist'' step to support your plugin's data generators. This avoids having to write new whole
new behat step definitions for your plugin, and allows you to re-use data generators between PHPUnit and Behat tests.

Full documentation of this process and all available options can be found in the [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/lib/behat/classes/behat_generator_base.php#L33 PHPDoc for behat_generator_base]. A core example of this can be found in [https://github.com/moodle/moodle/tree/master/mod/quiz/tests/generator /mod/quiz/tests/generator] and [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/mod/quiz/tests/behat/quiz_reset.feature#L51 quiz_reset.feature]. What follows is a simple example.

To begin, you need a [[Writing_PHPUnit_tests#Generators|generator]] in /''your''/''plugin''/tests/generator/lib.php. If you are generating a type of entity called "thing", your generator will need a method called create_thing, which accepts an object:

<code php>
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</code>

Next, you will need to define your behat generator in /''your''/''plugin''/tests/generator/behat_''your_plugin''_generator.php, with the method get_createable_entitites():

<code php>
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</code>

The 'datagenerator' value refers to the method in the generator class that we are calling, in this case ''create_thing()''. The outer array key is the entity name we will use in the behat step, in this case ''Given the following "local_myplugin > things" exist''.

Now, in your behat test, you can have a step like this, which will generate 2 ''things'', the first with the name "thing1" and the second with the name "thing2".

<code gherkin>
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

Note that this also implies that the Given, When and Then keywords should be used only once per scenario.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Writing acceptance tests

2020-08-19T09:12:33Z

Tim Hunt: /* Custom navigation targets (And I am on the "..." "..." page) */

== 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.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

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

== Create your 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:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
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:
<code behat>
@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
</code>
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:
<code behat>
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 |
</code>
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.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** icon - for searching an icon by its title
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** list_item - for searching a list item which contains the specified text
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== 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:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
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
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and 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 [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

==== Writing your own steps ====

Sometimes, you will need to set up data that is specific to your plugin, or perform steps that are specific to your plugin's UI. In this case it may be necessary to [[Writing_new_acceptance_test_step_definitions|write new step definitions]], but the short version is that you define new steps as PHP methods with a special annotation inside a class called <tt>behat_plugintype_plugingname</tt> inside tests/behat/behat_plugintype_plugingname.php in your plugin.

As well as creating completely new steps, you can also extend some of the standard steps:

===== Custom selectors (<tt>... in the "..." "..."</tt>) =====

There are a load of different steps which can refer to specific items on-screen, for example

And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"</code>

Here, 'button' and 'dialogue' are examples of selectors, and 'Submit all and finish' and 'Confirmation' are the locators which say which button or dialogue it is.

From Moodle 3.8 onwards, you can define new types of selector (for example <tt>core_message > Message</tt>) by implementing functions like <tt>behat_component_named_selector</tt> in your plugin's <tt>behat_plugintype_plugingname</tt> class.

The detailed instructions for how to do this are in [https://github.com/moodle/moodle/blob/33da028c27607354981cd8e62ecabb7b973c6637/lib/behat/behat_base.php#L1111 the PHPdoc comments on the base class].

===== Custom navigation targets (<tt>And I am on the "..." "..." page</tt>) =====

From Moodle 3.8 onwards,there are two related steps:

Given I am on the "Quiz 1" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page

To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you you needs to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about hwo this works are given in [https://github.com/moodle/moodle/blob/a0fc902eb184cd4097c8ab453ddc57964cd2dbd4/lib/behat/behat_base.php#L1093 the PHPdoc comments on the base class].

===== Custom entity generators (<tt>And the following "..." exist:</tt>) =====

From Moodle 3.8 onwards, it is possible to extend the ''Given the following "entites" exist'' step to support your plugin's data generators. This avoids having to write new whole
new behat step definitions for your plugin, and allows you to re-use data generators between PHPUnit and Behat tests.

Full documentation of this process and all available options can be found in the [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/lib/behat/classes/behat_generator_base.php#L33 PHPDoc for behat_generator_base]. A core example of this can be found in [https://github.com/moodle/moodle/tree/master/mod/quiz/tests/generator /mod/quiz/tests/generator] and [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/mod/quiz/tests/behat/quiz_reset.feature#L51 quiz_reset.feature]. What follows is a simple example.

To begin, you need a [[Writing_PHPUnit_tests#Generators|generator]] in /''your''/''plugin''/tests/generator/lib.php. If you are generating a type of entity called "thing", your generator will need a method called create_thing, which accepts an object:

<code php>
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</code>

Next, you will need to define your behat generator in /''your''/''plugin''/tests/generator/behat_''your_plugin''_generator.php, with the method get_createable_entitites():

<code php>
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</code>

The 'datagenerator' value refers to the method in the generator class that we are calling, in this case ''create_thing()''. The outer array key is the entity name we will use in the behat step, in this case ''Given the following "local_myplugin > things" exist''.

Now, in your behat test, you can have a step like this, which will generate 2 ''things'', the first with the name "thing1" and the second with the name "thing2".

<code gherkin>
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

Note that this also implies that the Given, When and Then keywords should be used only once per scenario.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Writing acceptance tests

2020-08-18T13:23:19Z

Tim Hunt: /* Writing your own steps */

== 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.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

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

== Create your 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:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
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:
<code behat>
@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
</code>
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:
<code behat>
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 |
</code>
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.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** icon - for searching an icon by its title
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** list_item - for searching a list item which contains the specified text
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== 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:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
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
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and 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 [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

==== Writing your own steps ====

Sometimes, you will need to set up data that is specific to your plugin, or perform steps that are specific to your plugin's UI. In this case it may be necessary to [[Writing_new_acceptance_test_step_definitions|write new step definitions]], but the short version is that you define new steps as PHP methods with a special annotation inside a class called <tt>behat_plugintype_plugingname</tt> inside tests/behat/behat_plugintype_plugingname.php in your plugin.

As well as creating completely new steps, you can also extend some of the standard steps:

===== Custom selectors (<tt>... in the "..." "..."</tt>) =====

There are a load of different steps which can refer to specific items on-screen, for example

And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"</code>

Here, 'button' and 'dialogue' are examples of selectors, and 'Submit all and finish' and 'Confirmation' are the locators which say which button or dialogue it is.

From Moodle 3.8 onwards, you can define new types of selector (for example <tt>core_message > Message</tt>) by implementing functions like <tt>behat_component_named_selector</tt> in your plugin's <tt>behat_plugintype_plugingname</tt> class.

The detailed instructions for how to do this are in [https://github.com/moodle/moodle/blob/33da028c27607354981cd8e62ecabb7b973c6637/lib/behat/behat_base.php#L1111 the PHPdoc comments on the base class].

===== Custom navigation targets (<tt>And I am on the "..." "..." page</tt>) =====

From Moodle 3.8 onwards,there are two related steps:

Given I am on the "iCMA51" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page

To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you you needs to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about hwo this works are given in [https://github.com/moodle/moodle/blob/a0fc902eb184cd4097c8ab453ddc57964cd2dbd4/lib/behat/behat_base.php#L1093 the PHPdoc comments on the base class].

===== Custom entity generators (<tt>And the following "..." exist:</tt>) =====

From Moodle 3.8 onwards, it is possible to extend the ''Given the following "entites" exist'' step to support your plugin's data generators. This avoids having to write new whole
new behat step definitions for your plugin, and allows you to re-use data generators between PHPUnit and Behat tests.

Full documentation of this process and all available options can be found in the [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/lib/behat/classes/behat_generator_base.php#L33 PHPDoc for behat_generator_base]. A core example of this can be found in [https://github.com/moodle/moodle/tree/master/mod/quiz/tests/generator /mod/quiz/tests/generator] and [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/mod/quiz/tests/behat/quiz_reset.feature#L51 quiz_reset.feature]. What follows is a simple example.

To begin, you need a [[Writing_PHPUnit_tests#Generators|generator]] in /''your''/''plugin''/tests/generator/lib.php. If you are generating a type of entity called "thing", your generator will need a method called create_thing, which accepts an object:

<code php>
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</code>

Next, you will need to define your behat generator in /''your''/''plugin''/tests/generator/behat_''your_plugin''_generator.php, with the method get_createable_entitites():

<code php>
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</code>

The 'datagenerator' value refers to the method in the generator class that we are calling, in this case ''create_thing()''. The outer array key is the entity name we will use in the behat step, in this case ''Given the following "local_myplugin > things" exist''.

Now, in your behat test, you can have a step like this, which will generate 2 ''things'', the first with the name "thing1" and the second with the name "thing2".

<code gherkin>
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

Note that this also implies that the Given, When and Then keywords should be used only once per scenario.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Writing acceptance tests

2020-08-18T13:22:57Z

Tim Hunt: /* Writing your own steps */

== 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.
This matches the standard [http://xunitpatterns.com/Four%20Phase%20Test.html Four-phase test pattern]. The fourth phase is 'tear-down' which we don't need because Behat automatically cleans up after each test.

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

== Create your 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:
<code behat>
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</code>
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:
<code behat>
@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
</code>
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:
<code behat>
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 |
</code>
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.

==== Providing values to steps ====
Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.

* '''A string/text'''; is the most common case, the texts are wrapped between double quotes (" character) you have to replace the info about the expected value for your value; for example something like '''I press "BUTTON_STRING"''' should become '''I press "Save and return to course"'''. If you want to add a string which contains a " character, you can escape it with \", for example '''I fill the "Name" field with "Alan alias \"the legend\""'''. You can identify this steps because they ends with '''_STRING'''
* '''A number'''; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with '''_NUMBER'''
* '''A table'''; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with ''':''' The steps description gives info about what the table columns must contain, for example '''Fills a moodle form with field/value data'''. Here you don't need to escape the double quotes if you want to include them as part of the value.
* '''A PyString'''; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"
* '''A field value'''; There are many different field types, if an argument requires a field value the expected value will depend on the field type:
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...
** Checkbox: It expects 1 to check and for checked and "" to uncheck or for unchecked
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: '''option1, option2, option3'''
** Radio: The text of the radio option
* '''A selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** field - for searching a field by its id, name, value or label
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** dialogue - for searching a dialogue with the specified header text
** filemanager - for searching a filemanager by it's id or label
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** icon - for searching an icon by its title
** fieldset - for searching a fieldset by it's id or legend
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath
* '''A text selector'''; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format '''... in the "Community finder" "block"''' where you are clicking or looking for some text inside a specific area. In the 'Acceptance testing' interface you can see a drop-down menu to select one of these options:
** dialogue - for searching a dialogue with the specified header text
** block - for searching a Moodle block by it's English name or it's frankenstyle name
** section - for searching for a section on a course page by it's title or its written out date (e.g. "1 January - 7 January"). Use "frontpage" "section" for the frontpage section if it has no title (default)
** activity - for searching for an activity module in a course list by it's title
** region - for searching a Moodle page region with that id, in fact it works with all ids for <tt>div</tt>, <tt>section</tt>, <tt>aside</tt>, <tt>header</tt> or <tt>footer</tt> elements.
** table_row - for searching a table row which contains the specified text
** table - for searching a table by its id or caption
** fieldset - for searching a fieldset by it's id or legend
** list_item - for searching a list item which contains the specified text
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

====== Checking table values ======
You can check if specific value exists or not in a table row/column by using:
* Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
* Then the following should exist in the "TABLE_ID" table:
| COLUMN_HEADER1 | COLUMN_HEADER2 |
| VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |
| VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |

==== 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:

====== Uploading files ======
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_file_upload''' tag
<code behat>
@editor @editor_atto @atto @atto_media @_file_upload
Feature: Add media to Atto
To write rich text - I need to add media.

Background:
Given I log in as "admin"
And I follow "Manage private files..."
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.webm" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.mp4" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/moodle-logo.png" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-en.vtt" file to "Files" filemanager
And I upload "lib/editor/atto/tests/fixtures/pretty-good-sv.vtt" file to "Files" filemanager
And I click on "Save changes" "button"
...
</code>

====== Field groups ======
This section describes how you can use the step definitions
<code behat>
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</code>
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
<code behat>
identifierOfYourField[keyOfTheSpecificInput]
</code>
Examples would be:
<code behat>
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</code>

====== Human-readable and 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 [http://php.net/manual/en/datetime.formats.php].

Especially useful are the relative formats from: [http://php.net/manual/en/datetime.formats.relative.php]

Additionally, you can specify a format you want the date to be returned into:
* ## yesterday ## myformat ##
These formats can be used as outlined in [http://php.net/manual/en/function.date.php].
This can be combined with the field groups:
<code behat>
When I set the following fields to these values:
| myDate[day] | ## yesterday ## j ## |
| myDate[month] | ## yesterday ## n ## |
| myDate[year] | ## yesterday ## Y ## |
</code>

==== Writing your own steps ====

Sometimes, you will need to set up data that is specific to your plugin, or perform steps that are specific to your plugin's UI. In this case it may be necessary to [[Writing_new_acceptance_test_step_definitions|write new step definitions]], but the short version is that you define new steps as PHP methods with a special annotation inside a class called <tt>behat_plugintype_plugingname</tt> inside tests/behat/behat_plugintype_plugingname.php in your plugin.

As well as creating completely new steps, you can also extend some of the standard steps:

===== Custom selectors (<tt>... in the "..." "..."</tt>) =====

There are a load of different steps which can refer to specific items on-screen, for example

And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"</code>

Here, 'button' and 'dialogue' are examples of selectors, and 'Submit all and finish' and 'Confirmation' are the locators which say which button or dialogue it is.

From Moodle 3.8 onwards, you can define new types of selector (for example <tt>core_message > Message</tt>) by implementing functions like <tt>behat_component_named_selector</tt> in your plugin's <tt>behat_plugintype_plugingname</tt> class.

The detailed instructions for how to do this are in [https://github.com/moodle/moodle/blob/33da028c27607354981cd8e62ecabb7b973c6637/lib/behat/behat_base.php#L1111 the PHPdoc comments on the base class].

===== Custom navigation targets (<tt>And I am on the "..." "..." page</tt>) =====

From Moodle 3.8 onwards,there are two related steps:

Given I am on the "iCMA51" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page

To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you you needs to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about hwo this works are given in [https://github.com/moodle/moodle/blob/a0fc902eb184cd4097c8ab453ddc57964cd2dbd4/lib/behat/behat_base.php#L1093 the PHPdoc comments on the base class].

===== Custom entity generators (<tt>And the following "..." exist:</tt>) =====

From Moodle 3.8 onwards, it is possible to extend the ''Given the following "entites" exist'' step to support your plugin's data generators. This avoids having to write new whole
new behat step definitions for your plugin, and allows you to re-use data generators between PHPUnit and Behat tests.

Full documentation of this process and all available options can be found in the [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/lib/behat/classes/behat_generator_base.php#L33 PHPDoc for behat_generator_base]. A core example of this can be found in [https://github.com/moodle/moodle/tree/master/mod/quiz/tests/generator /mod/quiz/tests/generator] and [https://github.com/moodle/moodle/blob/1d4fdb0d1c60448104bc9eac79b5123863c67cbd/mod/quiz/tests/behat/quiz_reset.feature#L51 quiz_reset.feature]. What follows is a simple example.

To begin, you need a [[Writing_PHPUnit_tests#Generators|generator]] in /''your''/''plugin''/tests/generator/lib.php. If you are generating a type of entity called "thing", your generator will need a method called create_thing, which accepts an object:

<code php>
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</code>

Next, you will need to define your behat generator in /''your''/''plugin''/tests/generator/behat_''your_plugin''_generator.php, with the method get_createable_entitites():

<code php>
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</code>

The 'datagenerator' value refers to the method in the generator class that we are calling, in this case ''create_thing()''. The outer array key is the entity name we will use in the behat step, in this case ''Given the following "local_myplugin > things" exist''.

Now, in your behat test, you can have a step like this, which will generate 2 ''things'', the first with the name "thing1" and the second with the name "thing2".

<code gherkin>
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</code>

== Good practice ==

=== Test one thing per scenario ===

The ideal that you should strive for, is that each scenario tests just one specific bit of functionality. Therefore, if one test fails, the scenario name should tell you exactly what the bug is. Also, any bug should cause just one scenario to fail, not lots of unrelated ones. If you can achieve this, then the idea is that it minimises the time from seeing a test fail to having fixed the bug that was detected. Of course, this ideal is not always achievable, but in my experience it is worth striving for.

Note that this also implies that the Given, When and Then keywords should be used only once per scenario.

=== Set-up (Given) should not use the UI ===

The setup is not what you are really testing here. Therefore, it should be as quick and reliable as possible. The way to achieve this is with steps like <tt>And the following "Thing" exist:</tt> which directly insert the data into the database. If necessary, write extra steps for your plugin to setup the things you need.

=== Don't use XPath or CSS selectors - fix your Accessibility bugs ===

If, the only way you can identify something in the page that you want to manipulate is with a step like <tt>I set the field with xpath "//textarea[contains(@name, 'answer')]" to "frog"</tt>, then this is probably the sign that you have an Accessibility bug, because Behat accesses the page very like a screen-reader user would.

You should be able to refer to things with steps like <tt>I set the field "Answer" to "frog"'</tt> or <tt>I click on "True" "radio" in the "First question" "question"</tt>. If not, you should probably think about fixing the accessibility bug, rather than resorting to unreadable selectors in your Behat test.

=== When you define more steps in your plugin, make it clear they come from your plugin ===

When defining new Step definitions in your plugin, try to make sure the step name identifies it as belonging to your plugin. So, don't make a step called <tt>I disable UI plugins</tt>. Call it something like <tt>I disable UI plugins in the CodeRunner question type</tt>.

[[Category:Behat]]

Peer reviewing

2020-06-19T14:37:13Z

Tim Hunt: /* Documentation */

=Process=

Peer review process helps to prepare the issue for integration. The peer reviewer is another developer who was not involved in the development process on the issue and therefore can take a fresh look and notice something that original developer might have forgotten during development. It is important to check that the bug actually is present and the code fixes it without creating new regressions.

==Completing Peer review as a community member==

Any other developer can review any change. That is why it is called 'peer' review. However, not everyone has the necessary permissions in the tracker to click the buttons 'Start peer review', 'Finish peer review' etc. This should not discourage you from looking at other contributors code and providing comments and feedback. The issue will still need to wait for someone with the right permissions to come along and click the buttons, but they can read your review and then need do no more than double-check some points, which will save a lot of time.

To provide feedback to the developer, leave the issue in "Waiting for Peer Review" (since you don't have permission to do anything else, and also that makes it easy for someone with sufficient permissions to find the issue and move it forwards). Review the code using the checklist below, including any appropriate comments. Once finished, please post a comment clearly stating the outcome of your review. If you think it needs more work then indicate what needs to be changed. If you are happy with the patch, leave a clear comment that you believe this is ready to be made part of Moodle. This can then easily be seen by a HQ developer or component lead and they can quickly take appropriate action.

If a followup review happens to identify something you did not find, you have an opportunity to expand your knowledge and provide better reviews in the future as well as having saved everybody else some time.

Feedback to indicate the issue is ready to progress might look like the following;

Thanks again for your contribution. I have reviewed the patch:
 
[Copy and paste the checklist here, and complete it]
 
I don't have permission to use the peer review buttons on this issue. I hope that someone with sufficient permissions will move the issue forwards soon.


Feedback to indicate the issue requires further work might look like the following;

Thanks for providing a patch. I think the following points require further work
 
[Copy and paste the checklist here, and complete it]
 
Please indicate If you are willing to continue working on this issue and complete the solution.


Can you help with peer reviewing? If so, please see the [https://tracker.moodle.org/issues/?filter=13607 list of issues waiting for peer review].

==Peer review for development by HQ or a known common contributor==

When code comes from a HQ developer or external developer who has been contributing significantly to Moodle and is well acquainted with Moodle standards, peer review is limited to checking the code according to the Checklist below.

If everything is fine, the peer reviewer submits the issue for integration.

If some additional work is needed or the author specifically asked not to submit for integration yet, the peer reviewer clicks on “Finish peer review” and the issue state returns to “Development in progress”. Usually the name of the peer reviewer stays on the issue and if a second peer review is requested it is expected that the same Peer reviewer picks it up. If the peer reviewer is not able to do the second review, they should remove their name and comment about it. Otherwise the issue does not appear on “waiting for peer review” dashboard. Please remember that not all jira users have permission to submit for integration.

==Peer review for external developers==

When the code has come from an external developer, the peer reviewer will also help the developer to lead the issue to integration. In this case the peer reviewer should not use “Finish peer review” button.

If the issue needs additional work, the peer reviewer comments about the suggested changes but does not change the status of the issue and it remains as “Peer review in progress”. If the author of the patch does not reply in 4 days, the peer reviewer may select either to complete the patch themselves or reopen the issue. The decision should be based on the amount of work required to complete the solution, for example, changing coding style or commit message, rebasing, backporting, adding testing instructions, etc. should be performed by the peer reviewer. This may require picking the commits into reviewer’s git branch.

It is very important to give the credit to the author of the code by either keeping their authorship on the commit or adding “Thanks to XXXX for providing the patch” to the commit message. If the author of the patch is not in jira-developers group the special user 'moodle.com' should be entered in Assignee field.

There could be situations when the patch is incomplete, does not fix the original issue, creates regressions or otherwise is not correct. As stated above, the peer reviewer should comment about it and wait for the feedback from the author. If there is no feedback, or the author can not work on this issue any more, and the peer reviewer also does not find it easy and important enough to complete, the issue needs to be reopened. Button “Fail peer review” (available to HQ developers only) will reset the issue status to “Reopened”. On this screen peer reviewer should remove assignee, peer reviewer and “patch” label from the issue. This way issue will become available again for anybody who want to work on it. All communication will remain in comments and issue history.

If the issue has passed peer review but the integrator or tester has raised some questions about it, then normally the developer who created the patch would be expected to respond. If they do no respond quickly enough, then the peer reviewer is expected to step in and take responsibility for the change they reviewed.

Once the issue is ready for integration, you can submit it to integration on behalf of the developer. Most external developers (those who are not in the jira-developers group) do not have permission to submit their own issues to integration so cannot do it themselves.

==Replies templates==


Thanks for providing a patch. 
I have reviewed your code and can confirm that it addresses the reported issue. We would like to include it in core. Moodle values its contributors and tries to give them credit when possible. If you are interested in your name appearing on the https://moodle.org/dev/contributions.php page you can create a git commit that we will then pull into Moodle. You can learn more about Git and how Moodle uses it at <nowiki>[Git for developers|https://docs.moodle.org/dev/Git_for_developers]</nowiki> page. Please let me know if you want to prepare a git branch. Or if you don’t have time to go through the whole process at the moment I can pick your patch myself.



Thanks for providing a patch. 
Your code looks almost ready for integration into Moodle. There are just some little things that need to be changed to comply with Moodle standards. Can you please take a look at the review results below and tell me if you are able to modify your branch to address them.



I have reviewed your patch, it addresses the problem and complies with Moodle standards. I'm pushing this issue for integration. Following Moodle <nowiki>[Process|https://docs.moodle.org/dev/Process]</nowiki> it will go through integration review and testing before being included in the product. There might be additional questions from an integrator and/or a tester at those stages. It would be appreciated if you read tracker emails and can reply to questions if needed. If everything goes well during the next two stages your issue will be included in the next weekly release and your count on https://moodle.org/dev/contributions.php page will increase. 
Thanks again for your contribution.



Thanks for providing a patch. 
Unfortunately this patch does not fully address the reported issue. ... DETAILS... 
Even though the code does solve the issue in the short-term it is very likely to create regressions ..... 
I have spent some time reviewing the patch and I would recommend that you ..... 
Please let me know If you are willing to continue working on this issue and complete the solution.


=Checklist=

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Privacy (see [[Privacy API]])
[] Performance and Clustering
[] Documentation
[] Git
[] Third party code
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.
Most of the previous items list are checked automatically by the CiBot ([[Automated code review]]). So in this case it's recommended to review the execution results to validate that there aren't errors. However, take into account that for now, CiBot is not checking all file types (it happens, for instance, with the Javascript files).

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid html5;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* [https://docs.moodle.org/dev/Commit_cheat_sheet#Include_AMOS_script_in_the_commit_if_needed AMOS commands] have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions:
** [[Testing instructions guide|are in the correct format]];
** are clear; and
** are concise;
* the assignee has tested according to the instructions and verified that they are passing (This is the responsibility of the assignee, not the peer reviewer)
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Privacy==
The user community relies on Moodle keeping user's privacy.

See more info [[Privacy_API]]

Ensure that:
* No unnecessary personal user data is saved;
* All personal user data is saved in compliance with [https://en.wikipedia.org/wiki/General_Data_Protection_Regulation General Data Protection Regulation] (GDPR) which is an EU directive;
* For all stored data you will need to:
** Describe the type of data that they store;
** Provide a way to export that data; and
** Provide a way to delete that data.

==Performance and clustering==
It is easy to write code that works sufficiently well when you are working on either small sets of data or with a small number of active users. Picking performance issues can be quite difficult and can required a complex level of understanding of both the section of code being reviewed, but also other parts that interact with it.

Clustering is when the same code is run on different computers and an end user could send each request to a different computer. This can produce a number of concurrency issues if not thought through. One example is; If you complete an opcache_reset(), no other server except the one you ran it on knows that it happened. So data can get out of sync.

Ensure that:
* Any filesystem, database or cache accesses are done in the most efficient way.
* That any code or function that appear expensive are not in critical paths. eg; They don't load on every page.
* The least possible code is running to complete the task, especially looking for hidden loops. They can appear from calling functions.
* Any code that runs is not specific to a single node. (eg opcache_reset()) This ensures clusters will run correctly.
* If the code could affect performance at all, make sure there is a comment noting what was considered.
** What they did to mitigate performance impact, or why they thought it wasn't an issue.
** Why they made certain trade-offs.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* The PHPdoc comments on all classes, methods and fields are useful. (Comments that just repeat the function name are not helpful! Add value.)
* Where an API has been changed significantly, the relevant upgrade.txt file has been updated with information.
* Where something has been deprecated, that the comments don't just say "do NOT use this any more!!!" but acutally say what should be done instead.
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_change),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly),
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly),
** unit_test_required and acceptance_test_required, when there are api or ui changes needing improved coverage, and
** qa_test_required (significant functional change, not covered by unit/acceptance ones).
* Also, verify that the components for the issue are correctly set, so maintainers (subscribed by default) will be mailed about issues early in the process.

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain [[Plugin with third party libraries|third party code]]? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.
* Any modifications to third party code are recorded in readme_moodle.txt

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* verify that the related component maintainers, if known, have participated and are aware of the issue (as assignee, or existing comments...). If they have not, please perform a friendly <tt>@mention</tt> to make them aware about the issue. A list of component leads is available here: https://docs.moodle.org/dev/Component_Leads
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].
* there are comments on tracker explaining why current approach was taken and why other options (especially large issues). If not comment asking them to explain

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

[[Category: Processes]]

Commit cheat sheet

2020-05-29T14:03:10Z

Tim Hunt: /* Split your work into a logical set of patches */

You can consider this page as a list to check before you submit a patch for inclusion into Moodle.

== Split your work into a logical set of patches ==

Keep in mind that your commits will be reviewed before they are accepted. If the patch does one clear thing and does it well, the review process is fun. Git allows you to prepare patches on your branch into a sequence of logical steps. For example, when changing some API, divide the change into two steps. In the first commit, change the API. In the following commit, change all places that use the API. <tt>git rebase -i</tt> is one of the commands you can use to do this.

== Provide clear commit messages ==

Consider the commit message as an email for the developer who would explore the change in the future. We recommend to follow common Git guidelines for formatting. The first line of commit message is generally treated as commit subject and should not exceed 72 characters. Include the MDL issue number and the area/component at the beginning of the subject line. Please note that 'code area' refers to the code areas being affected by this commit - correct the MDL's components reported against if needed. If you are writing more than one line, the second line must be empty. All the lines should though wrap at the 72nd mark. We can only hardly follow the [https://www.google.com/?q=git%2050/72%20rule 50/72 rule] in Moodle given the extra information expected at first (subject) line.

MDL-xxxxx code area: short description of the patch

The subject line is followed by an empty line and then a paragraph or two of
a longer description follows if necessary. This longer description is useful
for issues with longer history of comments in the linked MDL so that it
summarizes the patch without the need to go through the whole discussion.

Obviously, avoid messages like "as agreed in the chat" as they will become
useless after a relatively short time.

Most of Git tools are optimised for this format and they can display the log of commits best then.

::Tip: the command <tt>git log --no-merges</tt> will show you recent commit messages. Hopefully those are all good examples to copy.

== Names in the commit message ==

Retain the authorship of the patch. If the patch was submitted by someone else - for example a community member who published it in the tracker or in a forum - use the --author parameter. Make sure that your ''real'' name and contact email are recorded in patch. We use real names written in capital letters like "John Smith". Please do not use names like <strike>"john smith", "John S", "johnny7887"</strike>. If you use --author parameter, apply the same rules for the name of the author. See almost any Git tutorial on how to set your name and email in the global Git configuration.

== Provide clear and operational instructions to test your patch ==

In the tracker issue, please describe how the change can be tested. Please avoid vague phrases like "Make sure there is no regression in the core" or "Test all places where XXX is used". Also, try to avoid requiring resources that are really difficult to gather, if possible - as in "Use production data from a server with 100.000+ students".

If you have permission, edit the tracker issue and put the testing instructions into the "Testing instructions" field. If you do not have permission to edit that field, then write them in a comment on the tracker issue.

It helps if you state your estimation of the testing difficulty so that testers can pick issues for them:

;Easy : (average community member should be able to test it) - can be tested pretty easily via the web interface only at a public test site
;Moderate : (knowledgeable administrator should be able to test it) - requires local installation, for example to test some 1.9 -> 2.0 upgrade steps or some non-standard environment (for example MNet features, specific platform etc)
;Hard : (development skills are required to test it) - for example may require data hacking at SQL level to simulate data corruption or modifying the code to reproduce the problem

Example testing instructions:

(difficulty: easy, requires teacher access to a course)
1. Log in as a teacher and go to a course
2. Turn editing mode on
3. TEST: Make sure that the control icons appear next to the activity titles
4. Turn editing mode off
5. TEST: Make sure that the control icons are not displayed now

== Introducing new strings ==

Firstly, think twice and try to think in a non-English language. Any string you introduce is supposed to be translated by translators who usually do it for free in their own time. Do not waste their time by using get_string() for debugging messages that are likely to almost never appear. It is warmly recommended to let Helen review your strings before you submit them. This way we can keep the terminology and the style consistent. When introducing new strings, keep them alphabetically sorted. Using a self-descriptive names of the string identifier and the placeholder properties helps the translators to guess the context. Compare the following

<code php>
$string['grade'] = 'Grade {$a}';
</code>

with

<code php>
$string['maxgradevalue'] = 'Grade {$a->value}';
</code>

In the first case, it is pretty difficult to guess whether the "Grade" in the string is a noun (as in "Grade 12/30") or a verb (as in "Grade submission"). In many languages, the translation depends on it. The second case is more self-descriptive as it indicates that the placeholder will contain a value.

Another good example of how _not_ to name string identifiers would be something like

<code php>
$string['post'] = 'Post';
</code>

Note that there is no clue if the "post" here is used as a noun (e.g. describing one particular forum post) or a verb (such as an action of posting into a forum). In many languages, the translation is different for either case.

See [[Help strings]] if you are introducing a new help string.

== Include AMOS script in the commit if needed ==

If you change the identifier of a string or split a string into two forks, provide a script for AMOS in the commit message. Since Moodle 2.0, the translations are kept on separated branches again. The AMOS plugin at http://lang.moodle.org tracks the changes in string files and automatically records modifications, additions and removals of strings. Therefore strings can be re-worded freely on stable branches and should be removed from the master branch if they are not needed any more (do not remove strings from stable branches).

If you change the identifier of the string (that is the key in the $string array), move the string from one file to another or you are introducing a new string as a copy of some current one, you should provide instructions for AMOS so that the action can be applied in all language packs. That will save valuable translators' time. Instructions for AMOS are being put into the commit message of a commit that modifies the original English string files. The commit message containing such a script may look like this:

MDL-xxxxx code area: short description of the patch 
It is recommended to leave a blank line between the commit message and the
script block. 
AMOS BEGIN
MOV [configfoobar,core_admin],[foobar_desc,core_admin]
CPY [submission,mod_assignment],[submission,mod_workshop]
AMOS END

See [[Languages/AMOS#AMOS_script]] for more details of the syntax. See [http://git.moodle.org/gw?p=moodle.git&a=search&h=HEAD&st=commit&s=AMOS+BEGIN the log history] real examples of usage.

==Removing strings==

When a new feature completely replaces an existing feature, any strings which are no longer used should be removed from the code in the master branch. See [[String deprecation]] for more information.

== Main version changes ==

If your commit requires a change to the main version number in version.php (and corresponding upgrade in lib/db/upgrade.php), you should increment that version number by .01, and let integrators deal with merge conflicts (for example if multiple people that week submit several .01 updates).

(Note there may be policies about avoiding the type of changes which require version.php updates, especially in stable branches.)

[[Category:Git]]

Quiz database structure

2020-04-25T10:54:03Z

Tim Hunt: /* Quiz settings and runtime overview */

{{Quiz developer docs}}

This page documents the database tables used by the quiz module.

==Quiz settings and runtime overview==

It is helpful to distinguish between quiz settings, which is where we store information about how the teacher has set up the quiz, and 'runtime' (not a great name) where we store information about people's attempts at the quiz.

Note that information about the attempter's interaction with each question is [[Overview_of_the_Moodle_question_engine#Database_tables|stored by the question engine]].

Note: the diagram below is a bit out of date. The significant change is that quiz_question_instances has been renamed quiz_slots.
[[Image:Quiz_database.png|560px]]

[[Image:Quiz_database.dia]] [http://projects.gnome.org/dia/ Dia ] file, should you wish to have a copy of this diagram in an editable format.

==Common field types==

* Fields that hold an overall score, like quiz.grade, should be NUMBER(10,5).
* Fields that hold an individual question score, like quiz_question_instances.grade, should be NUMBER(12,7).

==Detailed table descriptions==

In Moodle 2.x dev, you can get these by going to Administration -> Development -> XMLDB and clicking on the [Doc] link next in any of the relevant rows (mod/quiz/db, mod/quiz/report/''xxx''/db). Looking directly there is much more likely to be up-to-date than relying on information that has been copied here.

(Wouldn't it be nice if that documentation was automatically built and available online.)

==Rough change-log==

===Moodle 2.3===

* New column quiz_attempts.currentpage for MDL-3054.
* New column quiz.navmethod for MDL-11047.
* New columns quiz.gradeperiod, quiz.overduehandling and quiz_attempts.state for MDL-3030.
* Old columns quiz_reports.cron and quiz_reports.lastcron dropped (MDL-30635). (config_plugins is now used, as for other plugin types.)

===Moodle 2.2===

* Old quiz.popup column replaced by quiz.browsersecurity

===Moodle 2.1 (new question engine)===

* Old quiz.optionflags and quiz.penaltyscheme columns replaced by quiz.preferredbehaviour.
* New quiz.showblocks column.
* Old quiz.review column split into seven new quiz.review* columns.

===Moodle 2.0===

* New field quiz.introformat.
* New field quiz.questiondecimalpoints.
* New field quiz.showuserpicture. See MDL-3156.
* All the quiz report tables are new. See [[Quiz_report_enhancements]]
* All fields that store grades were reviewed and set to the recommended types mentioned above.
* Never used quiz_question_versions table was removed.
* New table quiz_overrides for MDL-16478.

===Moodle 1.9===

* Time limit field changed to int(10).

===Moodle 1.7===

* New table quiz_feedback.

==See also==

* [[Question_database_structure| Question bank/engine database structure]]
* [[Database_schema_introduction|Database schema introduction]]

[[Category:Quiz]]

Quiz database structure

2020-04-25T10:53:52Z

Tim Hunt: /* Quiz settings and runtime overview */

{{Quiz developer docs}}

This page documents the database tables used by the quiz module.

==Quiz settings and runtime overview==

It is helpful to distinguish between quiz settings, which is where we store information about how the teacher has set up the quiz, and 'runtime' (not a great name) where we store information about people's attempts at the quiz.

Note that information about the attempter's interaction with each question is [[Overview_of_the_Moodle_question_engine#Database_tables|stored by the question engine]].

Note: the diagram below is a bit out of date. The significant change is that quiz_question_instances has been renamed quiz_slot.
[[Image:Quiz_database.png|560px]]

[[Image:Quiz_database.dia]] [http://projects.gnome.org/dia/ Dia ] file, should you wish to have a copy of this diagram in an editable format.

==Common field types==

* Fields that hold an overall score, like quiz.grade, should be NUMBER(10,5).
* Fields that hold an individual question score, like quiz_question_instances.grade, should be NUMBER(12,7).

==Detailed table descriptions==

In Moodle 2.x dev, you can get these by going to Administration -> Development -> XMLDB and clicking on the [Doc] link next in any of the relevant rows (mod/quiz/db, mod/quiz/report/''xxx''/db). Looking directly there is much more likely to be up-to-date than relying on information that has been copied here.

(Wouldn't it be nice if that documentation was automatically built and available online.)

==Rough change-log==

===Moodle 2.3===

* New column quiz_attempts.currentpage for MDL-3054.
* New column quiz.navmethod for MDL-11047.
* New columns quiz.gradeperiod, quiz.overduehandling and quiz_attempts.state for MDL-3030.
* Old columns quiz_reports.cron and quiz_reports.lastcron dropped (MDL-30635). (config_plugins is now used, as for other plugin types.)

===Moodle 2.2===

* Old quiz.popup column replaced by quiz.browsersecurity

===Moodle 2.1 (new question engine)===

* Old quiz.optionflags and quiz.penaltyscheme columns replaced by quiz.preferredbehaviour.
* New quiz.showblocks column.
* Old quiz.review column split into seven new quiz.review* columns.

===Moodle 2.0===

* New field quiz.introformat.
* New field quiz.questiondecimalpoints.
* New field quiz.showuserpicture. See MDL-3156.
* All the quiz report tables are new. See [[Quiz_report_enhancements]]
* All fields that store grades were reviewed and set to the recommended types mentioned above.
* Never used quiz_question_versions table was removed.
* New table quiz_overrides for MDL-16478.

===Moodle 1.9===

* Time limit field changed to int(10).

===Moodle 1.7===

* New table quiz_feedback.

==See also==

* [[Question_database_structure| Question bank/engine database structure]]
* [[Database_schema_introduction|Database schema introduction]]

[[Category:Quiz]]

External services description

2020-04-21T11:55:32Z

Tim Hunt: /* services.php */

{{Moodle_2.0}}

== Purpose ==
This document explains how we describe and where we store the external services and functions in Moodle 2.0.

===Service discovery===
We store the service descriptions and a part of the function descriptions in the component/db/services.php file. Function implementations are located in externallib.php files - this file name is not mandatory, but it is strongly recommended. externallib.php files also contain the other part of the function descriptions (the function parameters descriptions).

During the upgrades the descriptions are parsed by a service discovery function that fills the database tables. Administrative UI may be used to change some configuration details. Services can also be defined via the admin UI, but it is recommended to use the new local plugin (look at the readme.txt into the Moodle local folder) when adding custom new services.

===Administration pages===
Moodle administrators will be able to manage services. By default all services will be disabled.

List of administration functionalities:
* enable a service (all the functions into this service will be available)
* associate a web service user (the user has web service capability) to some services => a user can only call a service that he is associated with
* create a custom service (name the service + add and remove existing external functions from this service)
* search easily function by component in order to create a custom service

===external_functions table===
This table lists the web service functions. It makes sense to call it external_functions as 1 web service function <=> 1 external function. This table maps the web service function name to the actual implementation of that function.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''name'''
| varchar(200)
|
| the web service name (e.g. the unique name of the external function in the web service API) - a unique identifier for each function; ex.: core_get_users, mod_assignment_submit
|-
| classname
| varchar(100)
|
| name of the class that contains method implementation; ex.: core_user_external, mod_assignment_external
|-
| methodname
| varchar(100)
|
| static method; ex.: get_users, submit
|-
| classpath
| varchar(255)
| NULL
| optional path to file with class definition - recommended for core classes only, null means use component/externallib.php; this path is relative to dirroot; ex.: user/externallib.php
|-
| component
| varchar(100)
|
| Component where function defined, needed for automatic updates. Service description file is found in the db folder of this component.
|-
| description
| text
|
| A short human readable description of the function. It will be used to generate documentation and help the administrator to search a web service function. (NB: decide later if it's really improving the performance compare to add an access to the phpfile)
|}

Detailed function description is stored as a complex PHP structure in the implementation class using suffix _parameters and _returns.

===external_services table===
A ''service'' is defined as a group of external functions. The main purpose of these ''services'' is to allow defining of granular access control for multiple external systems.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''name'''
| varchar(150)
|
| Name of service (gradeexport_xml_export, mod_chat_export) - appears on the admin page. This name is not human readable when displayed into administration. We will use lang file to translate them automatically if a lang string exist.
|-
| enabled
| int(1)
| 0
| service enabled, for security reasons some services may be disabled- administrators may disable any service via the admin UI
|-
| requiredcapability
| varchar(255)
| NULL
| if capability name specified, user needs to have this permission in security context or in system context if context restriction not specified
|-
| restrictedusers
| int(1)
| 1
| 1 means on users explicitly listed in external_services_users may access this service, 0 means any user may use this service
|-
| component
| varchar(100)
| NULL
| Component where service defined - null means custom service defined in admin UI.
|-
| timecreated
| bigint(10)
|
| The time the service was enabled or defined?
|-
| timemodified
| bigint(10)
|
| The last time the service was updated
|-
| shortname
| varchar(255)
|
| The short name of the service
|-
| downloadfiles
| tinyint(1)
|
| A flag for something to do with download and files?
|}

===external_services_functions table===
Lists all functions that are available in each service.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''externalserviceid'''
| int(10)
|
| foreign key, reference external_services.id
|-
| '''functionname'''
| varchar(200)
|
| unique name of external function: references external_functions.name; the string value here simplifies service discovery and maintenance
|}

=== Function description ===

We need to describe each function in detail, including input and output, so that we can:

* help programmers quickly understand what they have to send and what to expect
* validate all incoming data as automatically as possible for security/correctness
* generate WSDL files for SOAP
* generate documentation for other protocols

There are three main parts working together to do this:

====services.php====

In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions.

<code php>
$functions = array(
'moodle_user_create_users' => array( //web service name (unique in all Moodle)
'classname' => 'moodle_user_external', //class containing the function implementation
'methodname' => 'create_users', //name of the function into the class
'classpath' => 'user/externallib.php', //file containing the class (only used for core external function, not needed if your file is 'component/externallib.php'),
'description' => 'create some users',
'type' => 'write',
'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE) // Optional, only available for Moodle 3.1 onwards. List of built-in services (by shortname) where the function will be included. Services created manually via the Moodle interface are not supported.
)
);

$services = array(
'servicename' => array(
'functions' => array ('functionname', 'secondfunctionname'), //web service function name
'requiredcapability' => 'some/capability:specified',
'restrictedusers' => 1,
'enabled'=>0, //used only when installing the services
)
);
</code>

The function name is arbitrary, but must follow [[Web_service_API_functions#Naming_convention|the naming convention]]. This helps ensure that it is globally unique.

The actual param description and description of returned values can be obtained from the same class by static method calls by adding '_parameters' and '_returns' to the methodname value.

====externallib.php====

It's the file referenced as the location for the web service function implementation. It also contains complete descriptions of the required parameters.

''Base description classes:''
<code php>
abstract class external_description {
public $desc; //human readable description
public $required;

public function __construct($desc, $required) {
$this->desc = $desc;
$this->required = $required;
}
}

class external_value extends external_description {
public $type;
public $default;
public $allownull;

public function __construct($type, $desc='', $required=VALUE_REQUIRED, $default=null, $allownull=true) {
parent::_construct($desc, $required);
$this->type = $type;
$this->default = $default;
$this->allownull = $allownull;
}
}

class external_single_structure extends external_description {
public $keys; //an associative array of external_description

public function __construct(array $keys, $desc='', $required=VALUE_REQUIRED) {
parent::_construct($desc, $required);
$this->keys = $keys; //key=>external_description
}
}

class external_multiple_structure extends external_description {
public $content; //the content type of the list => external_description

public function __construct(external_description $content, $desc='', $required=VALUE_REQUIRED) {
parent::_construct($desc, $required);
$this->content = $content;
}
}

class external_function_parameters extends external_single_structure {
}

</code>

''Externallib.php examples:'' 
These examples include param/return value descriptions and function implementations. See the create_users function for difference between Mandatory/Optional/Default.
<code php>
class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class
public static function add_member_parameters() {
return new external_function_parameters(
array(
'groupid' => new external_value(PARAM_INT, 'some group id'),
'userid' => new external_value(PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_parameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() {
return null;
}

public static function add_members_parameters() {
return new external_function_parameters(
array(
'membership' => new external_multiple_structure(
self::add_member_parameters()
)
)
);
}
public static function add_members(array $membership) {
$params = self::validate_parameters(self::add_members_parameters(), array('membership'=>$membership));
foreach($params['membership'] as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() {
return null;
}

public static function get_groups_parameters() {
return new external_function_parameters(
array(
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'groupid' => new external_value(PARAM_INT, 'some group id')
)
)
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_parameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if needed and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'some group id'),
'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
'description' => new external_value(PARAM_RAW, 'just some text'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
new external_function_parameters(
array(
'users' => new external_multiple_structure(
new external_single_structure(
array(
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'),
'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
'auth' => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap,
imap, etc', VALUE_DEFAULT,'manual', false),
'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution',
VALUE_DEFAULT, null),
'emailstop' => new external_value(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise',
VALUE_DEFAULT, 0),
'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en_utf8" must exist on server',
VALUE_DEFAULT, $CFG->lang, false),
'theme' => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard" must exist on server',
VALUE_OPTIONAL),
'timezone' => new external_value(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth,or 99 for default',
VALUE_OPTIONAL),
'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc',
VALUE_OPTIONAL),
'description' => new external_value(PARAM_TEXT, 'User profile description, as HTML', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ',
VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
'value' => new external_value(PARAM_RAW, 'The value of the preference')
)
), 'User preferences', VALUE_OPTIONAL),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', VALUE_OPTIONAL)
)
)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));

foreach ($params['users'] as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() {
return new external_multiple_structure(
new external_value('userid', PARAM_INT, 'id of the created user')
);
}
}
</code>

Note the use of Moodle-oriented PARAM_XXXX constants to define the format of each field. These are used by the validation function ''validate_parameters()'' to verify the data and throw an exception and abort the operation completely if the data changed during cleaning (ie it was malformed).

====Params====

We use the clean_param function to check data. We have added in ''moodlelib.php'' some new checks for common Moodle data so that we get better cleaning. eg

<code php>
...
case PARAM_AUTH:
$param = clean_param($param, PARAM_SAFEDIR);
if (exists_auth_plugin($param)) {
return $param;
} else {
return '';
}

case PARAM_LANG:
$param = clean_param($param, PARAM_SAFEDIR);
$langs = get_list_of_languages(false, true);
if (in_array($param, $langs)) {
return $param;
} else {
return ''; // Specified language is not installed
}

case PARAM_THEME:
$param = clean_param($param, PARAM_SAFEDIR);
if (file_exists($CFG->dirroot.'/theme/'.$param)) {
return $param;
} else {
return ''; // Specified theme is not installed
}
...
</code>

=====Parameters types=====

Note, this list will almost certainly be out of date by the time you read it. Do yourself a favour, and look at the list in lib/moodlelib.php. That is guaranteed to be up-to-date.

* 'PARAM_ALPHA', 'alpha'
* 'PARAM_ALPHAEXT', 'alphaext'
* 'PARAM_ALPHANUM', 'alphanum'
* 'PARAM_ALPHANUMEXT', 'alphanumext'
* 'PARAM_AUTH', 'auth'
* 'PARAM_BASE64', 'base64'
* 'PARAM_BOOL', 'bool'
* 'PARAM_CAPABILITY', 'capability'
* 'PARAM_CLEANHTML', 'cleanhtml'
* 'PARAM_EMAIL', 'email'
* 'PARAM_FILE', 'file'
* 'PARAM_FLOAT', 'float'
* 'PARAM_HOST', 'host'
* 'PARAM_INT', 'int'
* 'PARAM_LANG', 'lang'
* 'PARAM_LOCALURL', 'localurl'
* 'PARAM_NOTAGS', 'notags'
* 'PARAM_PATH', 'path'
* 'PARAM_PEM', 'pem'
* 'PARAM_PERMISSION', 'permission'
* 'PARAM_RAW', 'raw'
* 'PARAM_RAW_TRIMMED', 'raw_trimmed'
* 'PARAM_SAFEDIR', 'safedir'
* 'PARAM_SAFEPATH', 'safepath'
* 'PARAM_SEQUENCE', 'sequence'
* 'PARAM_TAG', 'tag'
* 'PARAM_TAGLIST', 'taglist'
* 'PARAM_TEXT', 'text'
* 'PARAM_THEME', 'theme'
* 'PARAM_URL', 'url'
* 'PARAM_USERNAME', 'username'
* 'PARAM_STRINGID', 'stringid'
* 'PARAM_CLEAN', 'clean'
* 'PARAM_INTEGER', 'int'
* 'PARAM_NUMBER', 'float'
* 'PARAM_ACTION', 'alphanumext'
* 'PARAM_FORMAT', 'alphanumext'
* 'PARAM_MULTILANG', 'text'
* 'PARAM_TIMEZONE', 'timezone'
* 'PARAM_CLEANFILE', 'file'
* 'PARAM_COMPONENT', 'component'
* 'PARAM_AREA', 'area'
* 'PARAM_PLUGIN', 'plugin'

=== Function implementation ===

As you probably understood when you read the previous chapter examples, the functions are generally stored in externallib.php files, as methods in a class that extends ''''external_api''''. The actual file location is referenced by ''''classpath'''' in the services.php description.

<code php>
class moodle_user_external extends external_api {
public static function create_users($users)
$params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users)); //ws object are associative array, ws list are non associative array

foreach ($params['users'] as $user) {
// all the parameter/behavioural checks and security constraints go here,
// throwing exceptions if needed and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
}
</code>

Note: there is more examples in the previous chapter

external_api file:
<code php>
/**
* Base class for external api methods.
*/
class external_api {

...

/**
* Validates submitted function parameters, if anything is incorrect
* invalid_parameter_exception is thrown.
* This is a simple recursive method which is intended to be called from
* each implementation method of external API.
* @param external_description $description description of parameters
* @param mixed $params the actual parameters
* @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
*/
public static function validate_parameters(external_description $description, $params) {
...
}

...
}
</code>

=== Way to fill the database tables ===
The Moodle upgrade takes care of the updates. We added two functions ''lib/upgradelib.php/external_update_description()'' and ''lib/upgradelib.php/external_delete_description()'' that update all web service descriptions into the database. ''lib/upgradelib.php/external_update_description()'' is also called during Moodle installation process.

=== Return values are filtered by the servers ===
Web service functions should be able to return whatever they want. Each server should be looking at the web services description and returns the expected values.

Some bulk requests may terminate unexpectedly in the middle of processing elements, these partial failures should be indicated by special exceptions classes which include list of completed elements and original exception. TODO: special exceptions and the way to manage them need to be detailed

=See also=
* [[Web services]]
* [[External services security]]

[[Category:Web Services]]

External services description

2020-04-21T11:53:53Z

Tim Hunt: /* services.php */

{{Moodle_2.0}}

== Purpose ==
This document explains how we describe and where we store the external services and functions in Moodle 2.0.

===Service discovery===
We store the service descriptions and a part of the function descriptions in the component/db/services.php file. Function implementations are located in externallib.php files - this file name is not mandatory, but it is strongly recommended. externallib.php files also contain the other part of the function descriptions (the function parameters descriptions).

During the upgrades the descriptions are parsed by a service discovery function that fills the database tables. Administrative UI may be used to change some configuration details. Services can also be defined via the admin UI, but it is recommended to use the new local plugin (look at the readme.txt into the Moodle local folder) when adding custom new services.

===Administration pages===
Moodle administrators will be able to manage services. By default all services will be disabled.

List of administration functionalities:
* enable a service (all the functions into this service will be available)
* associate a web service user (the user has web service capability) to some services => a user can only call a service that he is associated with
* create a custom service (name the service + add and remove existing external functions from this service)
* search easily function by component in order to create a custom service

===external_functions table===
This table lists the web service functions. It makes sense to call it external_functions as 1 web service function <=> 1 external function. This table maps the web service function name to the actual implementation of that function.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''name'''
| varchar(200)
|
| the web service name (e.g. the unique name of the external function in the web service API) - a unique identifier for each function; ex.: core_get_users, mod_assignment_submit
|-
| classname
| varchar(100)
|
| name of the class that contains method implementation; ex.: core_user_external, mod_assignment_external
|-
| methodname
| varchar(100)
|
| static method; ex.: get_users, submit
|-
| classpath
| varchar(255)
| NULL
| optional path to file with class definition - recommended for core classes only, null means use component/externallib.php; this path is relative to dirroot; ex.: user/externallib.php
|-
| component
| varchar(100)
|
| Component where function defined, needed for automatic updates. Service description file is found in the db folder of this component.
|-
| description
| text
|
| A short human readable description of the function. It will be used to generate documentation and help the administrator to search a web service function. (NB: decide later if it's really improving the performance compare to add an access to the phpfile)
|}

Detailed function description is stored as a complex PHP structure in the implementation class using suffix _parameters and _returns.

===external_services table===
A ''service'' is defined as a group of external functions. The main purpose of these ''services'' is to allow defining of granular access control for multiple external systems.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''name'''
| varchar(150)
|
| Name of service (gradeexport_xml_export, mod_chat_export) - appears on the admin page. This name is not human readable when displayed into administration. We will use lang file to translate them automatically if a lang string exist.
|-
| enabled
| int(1)
| 0
| service enabled, for security reasons some services may be disabled- administrators may disable any service via the admin UI
|-
| requiredcapability
| varchar(255)
| NULL
| if capability name specified, user needs to have this permission in security context or in system context if context restriction not specified
|-
| restrictedusers
| int(1)
| 1
| 1 means on users explicitly listed in external_services_users may access this service, 0 means any user may use this service
|-
| component
| varchar(100)
| NULL
| Component where service defined - null means custom service defined in admin UI.
|-
| timecreated
| bigint(10)
|
| The time the service was enabled or defined?
|-
| timemodified
| bigint(10)
|
| The last time the service was updated
|-
| shortname
| varchar(255)
|
| The short name of the service
|-
| downloadfiles
| tinyint(1)
|
| A flag for something to do with download and files?
|}

===external_services_functions table===
Lists all functions that are available in each service.

{| class="nicetable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''externalserviceid'''
| int(10)
|
| foreign key, reference external_services.id
|-
| '''functionname'''
| varchar(200)
|
| unique name of external function: references external_functions.name; the string value here simplifies service discovery and maintenance
|}

=== Function description ===

We need to describe each function in detail, including input and output, so that we can:

* help programmers quickly understand what they have to send and what to expect
* validate all incoming data as automatically as possible for security/correctness
* generate WSDL files for SOAP
* generate documentation for other protocols

There are three main parts working together to do this:

====services.php====

In the db/services.php of each component, is a structure something like this to describe the web service functions, and optionally, any larger services built up of several functions.

<code php>
$functions = array(
'moodle_user_create_users' => array( //web service name (unique in all Moodle)
'classname' => 'moodle_user_external', //class containing the function implementation
'methodname' => 'create_users', //name of the function into the class
'classpath' => 'user/externallib.php', //file containing the class (only used for core external function, not needed if your file is 'component/externallib.php'),
'description' => 'create some users',
'type' => 'write',
'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE) // Optional, only available for Moodle 3.1 onwards. List of built-in services (by shortname) where the function will be included. Services created manually via the Moodle interface are not supported.
)
);

$services = array(
'servicename' => array(
'functions' => array ('functionname', 'secondfunctionname'), //web service function name
'requiredcapability' => 'some/capability:specified',
'restrictedusers' => 1,
'enabled'=>0, //used only when installing the services
)
);
</code>

The function name is arbitrary, but it must be globally unique so we highly recommend using the component name as prefix (and "moodle" for core functions).

The actual param description and description of returned values can be obtained from the same class by static method calls by adding '_parameters' and '_returns' to the methodname value.

====externallib.php====

It's the file referenced as the location for the web service function implementation. It also contains complete descriptions of the required parameters.

''Base description classes:''
<code php>
abstract class external_description {
public $desc; //human readable description
public $required;

public function __construct($desc, $required) {
$this->desc = $desc;
$this->required = $required;
}
}

class external_value extends external_description {
public $type;
public $default;
public $allownull;

public function __construct($type, $desc='', $required=VALUE_REQUIRED, $default=null, $allownull=true) {
parent::_construct($desc, $required);
$this->type = $type;
$this->default = $default;
$this->allownull = $allownull;
}
}

class external_single_structure extends external_description {
public $keys; //an associative array of external_description

public function __construct(array $keys, $desc='', $required=VALUE_REQUIRED) {
parent::_construct($desc, $required);
$this->keys = $keys; //key=>external_description
}
}

class external_multiple_structure extends external_description {
public $content; //the content type of the list => external_description

public function __construct(external_description $content, $desc='', $required=VALUE_REQUIRED) {
parent::_construct($desc, $required);
$this->content = $content;
}
}

class external_function_parameters extends external_single_structure {
}

</code>

''Externallib.php examples:'' 
These examples include param/return value descriptions and function implementations. See the create_users function for difference between Mandatory/Optional/Default.
<code php>
class moodle_group_external extends external_api { //see following chapter 'function implementation' to have a look to the external_api class
public static function add_member_parameters() {
return new external_function_parameters(
array(
'groupid' => new external_value(PARAM_INT, 'some group id'),
'userid' => new external_value(PARAM_INT, 'some user id')
)
);
}
public static function add_member($groupid, $userid) {
$params = self::validate_parameters(self::add_member_parameters(), array('groupid'=>$groupid, 'userid'=>$userid));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (grouplib)
// add_member() function that will be one in charge of the functionality without
// further checks.

}
public static function add_member_returns() {
return null;
}

public static function add_members_parameters() {
return new external_function_parameters(
array(
'membership' => new external_multiple_structure(
self::add_member_parameters()
)
)
);
}
public static function add_members(array $membership) {
$params = self::validate_parameters(self::add_members_parameters(), array('membership'=>$membership));
foreach($params['membership'] as $one) { // simply one iterator over the "single" function if possible
self::add_member($one->groupid, $one->userid);
}
}
public static function add_members_returns() {
return null;
}

public static function get_groups_parameters() {
return new external_function_parameters(
array(
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'groupid' => new external_value(PARAM_INT, 'some group id')
)
)
)
)
);
}
public static function get_groups(array $groups) {
$params = self::validate_parameters(self::get_groups_parameters(), array('groups'=>$groups));

// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if needed and and calling low level (grouplib)
// get_groups() function that will be one in charge of the functionality without
// further checks.

}
public static function get_groups_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'some group id'),
'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
'description' => new external_value(PARAM_RAW, 'just some text'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase')
)
)
);
}
}

class moodle_user_external extends external_api {
public static function create_users_parameters() {
new external_function_parameters(
array(
'users' => new external_multiple_structure(
new external_single_structure(
array(
'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'),
'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
'auth' => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap,
imap, etc', VALUE_DEFAULT,'manual', false),
'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution',
VALUE_DEFAULT, null),
'emailstop' => new external_value(PARAM_NUMBER, 'Email is blocked: 1 is blocked and 0 otherwise',
VALUE_DEFAULT, 0),
'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en_utf8" must exist on server',
VALUE_DEFAULT, $CFG->lang, false),
'theme' => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard" must exist on server',
VALUE_OPTIONAL),
'timezone' => new external_value(PARAM_ALPHANUMEXT, 'Timezone code such as Australia/Perth,or 99 for default',
VALUE_OPTIONAL),
'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc',
VALUE_OPTIONAL),
'description' => new external_value(PARAM_TEXT, 'User profile description, as HTML', VALUE_OPTIONAL),
'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ',
VALUE_OPTIONAL),
'preferences' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
'value' => new external_value(PARAM_RAW, 'The value of the preference')
)
), 'User preferences', VALUE_OPTIONAL),
'customfields' => new external_multiple_structure(
new external_single_structure(
array(
'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
'value' => new external_value(PARAM_RAW, 'The value of the custom field')
)
), 'User custom fields', VALUE_OPTIONAL)
)
)
)
)
);
}
public static function create_users(array $users) {
$params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));

foreach ($params['users'] as $user) {
// all the parameter/behavioural checks and security constrainsts go here,
// throwing exceptions if neeeded and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
public static function create_users_returns() {
return new external_multiple_structure(
new external_value('userid', PARAM_INT, 'id of the created user')
);
}
}
</code>

Note the use of Moodle-oriented PARAM_XXXX constants to define the format of each field. These are used by the validation function ''validate_parameters()'' to verify the data and throw an exception and abort the operation completely if the data changed during cleaning (ie it was malformed).

====Params====

We use the clean_param function to check data. We have added in ''moodlelib.php'' some new checks for common Moodle data so that we get better cleaning. eg

<code php>
...
case PARAM_AUTH:
$param = clean_param($param, PARAM_SAFEDIR);
if (exists_auth_plugin($param)) {
return $param;
} else {
return '';
}

case PARAM_LANG:
$param = clean_param($param, PARAM_SAFEDIR);
$langs = get_list_of_languages(false, true);
if (in_array($param, $langs)) {
return $param;
} else {
return ''; // Specified language is not installed
}

case PARAM_THEME:
$param = clean_param($param, PARAM_SAFEDIR);
if (file_exists($CFG->dirroot.'/theme/'.$param)) {
return $param;
} else {
return ''; // Specified theme is not installed
}
...
</code>

=====Parameters types=====

Note, this list will almost certainly be out of date by the time you read it. Do yourself a favour, and look at the list in lib/moodlelib.php. That is guaranteed to be up-to-date.

* 'PARAM_ALPHA', 'alpha'
* 'PARAM_ALPHAEXT', 'alphaext'
* 'PARAM_ALPHANUM', 'alphanum'
* 'PARAM_ALPHANUMEXT', 'alphanumext'
* 'PARAM_AUTH', 'auth'
* 'PARAM_BASE64', 'base64'
* 'PARAM_BOOL', 'bool'
* 'PARAM_CAPABILITY', 'capability'
* 'PARAM_CLEANHTML', 'cleanhtml'
* 'PARAM_EMAIL', 'email'
* 'PARAM_FILE', 'file'
* 'PARAM_FLOAT', 'float'
* 'PARAM_HOST', 'host'
* 'PARAM_INT', 'int'
* 'PARAM_LANG', 'lang'
* 'PARAM_LOCALURL', 'localurl'
* 'PARAM_NOTAGS', 'notags'
* 'PARAM_PATH', 'path'
* 'PARAM_PEM', 'pem'
* 'PARAM_PERMISSION', 'permission'
* 'PARAM_RAW', 'raw'
* 'PARAM_RAW_TRIMMED', 'raw_trimmed'
* 'PARAM_SAFEDIR', 'safedir'
* 'PARAM_SAFEPATH', 'safepath'
* 'PARAM_SEQUENCE', 'sequence'
* 'PARAM_TAG', 'tag'
* 'PARAM_TAGLIST', 'taglist'
* 'PARAM_TEXT', 'text'
* 'PARAM_THEME', 'theme'
* 'PARAM_URL', 'url'
* 'PARAM_USERNAME', 'username'
* 'PARAM_STRINGID', 'stringid'
* 'PARAM_CLEAN', 'clean'
* 'PARAM_INTEGER', 'int'
* 'PARAM_NUMBER', 'float'
* 'PARAM_ACTION', 'alphanumext'
* 'PARAM_FORMAT', 'alphanumext'
* 'PARAM_MULTILANG', 'text'
* 'PARAM_TIMEZONE', 'timezone'
* 'PARAM_CLEANFILE', 'file'
* 'PARAM_COMPONENT', 'component'
* 'PARAM_AREA', 'area'
* 'PARAM_PLUGIN', 'plugin'

=== Function implementation ===

As you probably understood when you read the previous chapter examples, the functions are generally stored in externallib.php files, as methods in a class that extends ''''external_api''''. The actual file location is referenced by ''''classpath'''' in the services.php description.

<code php>
class moodle_user_external extends external_api {
public static function create_users($users)
$params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users)); //ws object are associative array, ws list are non associative array

foreach ($params['users'] as $user) {
// all the parameter/behavioural checks and security constraints go here,
// throwing exceptions if needed and and calling low level (userlib)
// add_user() function that will be one in charge of the functionality without
// further checks.
}
}
}
</code>

Note: there is more examples in the previous chapter

external_api file:
<code php>
/**
* Base class for external api methods.
*/
class external_api {

...

/**
* Validates submitted function parameters, if anything is incorrect
* invalid_parameter_exception is thrown.
* This is a simple recursive method which is intended to be called from
* each implementation method of external API.
* @param external_description $description description of parameters
* @param mixed $params the actual parameters
* @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
*/
public static function validate_parameters(external_description $description, $params) {
...
}

...
}
</code>

=== Way to fill the database tables ===
The Moodle upgrade takes care of the updates. We added two functions ''lib/upgradelib.php/external_update_description()'' and ''lib/upgradelib.php/external_delete_description()'' that update all web service descriptions into the database. ''lib/upgradelib.php/external_update_description()'' is also called during Moodle installation process.

=== Return values are filtered by the servers ===
Web service functions should be able to return whatever they want. Each server should be looking at the web services description and returns the expected values.

Some bulk requests may terminate unexpectedly in the middle of processing elements, these partial failures should be indicated by special exceptions classes which include list of completed elements and original exception. TODO: special exceptions and the way to manage them need to be detailed

=See also=
* [[Web services]]
* [[External services security]]

[[Category:Web Services]]

Running acceptance test

2020-04-20T16:18:34Z

Tim Hunt: /* Trouble shooting */

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====
First, you should have a look at [[Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium#Working_combinations_of_OS.2BBrowser.2Bselenium|working combinations of OS+Browser+selenium]].

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/]. Ensure you have the right version of the Chrome driver - see [[#Trouble_shooting| Trouble shooting]]. (Firefox is currently problematic. See [[Actual_Selenium_with_old_Firefox_47.0.1]] if you need to try to make it work.)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j=<number> or --parallel=<number>''' (required) Number of parallel behat run to initialise
# '''-m=<number> or --maxruns=<number>''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun=<number>''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun=<number>''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a=<name> or --add-core-features-to-theme=<name>''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

You almost always want to limit the number of tests that are run. To run all the tests in one plugin:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin
</code>

To run all the tests in one .feature file:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature
</code>

To run a single scenario:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature:40
</code>

Here, '40' is the line-number of the feature file where the Scenario starts.

=== Parallel runs ===
For running parallel runs, use following command

php admin/tool/behat/cli/run.php

Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

Example: Initialise and run Behat tests for a custom plugin under a custom theme:

php admin/tool/behat/cli/init.php --parallel=3 --add-core-features-to-theme="mytheme"
php admin/tool/behat/cli/run.php --tags="@tool_myplugin" --suite="mytheme"

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" iframe''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with --add-core-features-to-theme={THEME_NAME}, e.g.

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===

If you follow the steps above, Behat will run with Chrome.

You can get it to run with other browsers. The basic idea is to expand the $CFG->behat_profiles array in config.php to list more browsers.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>

[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== Trouble shooting ==

=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===

If you followed all the steps and you receive an unknown weird error probably your browser version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== The tests are failing, and the error message is completely useless ===

For example, it just says "Error writing to database" with no stack trace.

Add -vv command-line option to get very verbose output.

=== Errors during setup (before test are launched) ===
Typical errors are:
* Behat requirement not satisfied: http://127.0.0.1/m/stable_master is not available, ensure you specified correct url and that the server is set up and started.
* Behat is configured but not enabled on this test site.

In order to fix those errors please check that: the behat_dataroot has correct write permissions and that the $CFG->behat* variables are placed before the lib/setup.php include:
require_once(__DIR__ . '/lib/setup.php');

=== Selenium server is not running ===
==== Chrome specific ====

If you are using chrome, you need to ensure that the driver matches the version of the installed chrome browser – which may change on OS updates/upgrades. Moodle or Selenium will not give the appropriate message – see [https://tracker.moodle.org/browse/MDL-67659/ MDL-67659]. One solution is the one suggested in the issue and use Andrew Nicols’ [https://github.com/andrewnicols/chromedriver-wrapper/ Chromedriver Wrapper] which will ensure you have the appropriate driver before running the tests.

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

== See also ==
* [[Acceptance testing for the mobile app]]

[[Category:Quality Assurance]][[Category:Behat]]

Cache API

2020-04-16T12:01:19Z

Tim Hunt: /* Using time as a key suffix */

This document details the Cache API aka MUC aka Moodle's Universal Cache.
I've chosen to use a tutorial/example flow for this document always working with a theoretical module plugin called myplugin.
There is also a [[Cache API - Quick reference]] if you would rather read that.

==Basic usage==
It's very easy to get started with the Cache API. It is designed to be as easy and as quick to use as possible and is predominantely self contained.
All you need to do is add a definition for your cache and you are ready to start working with the Cache API.

===Creating a definition===
Cache definitions exist within the db/caches.php file for a component/plugin. 
In the case of core that is the moodle/lib/db/caches.php file, in the case of a module that would be moodle/mod/myplugin/db/caches.php.

The definition is used API in order to understand a little about the cache and what it is being used for, it also allows the administrator to set things up especially for the definition if they want.
From a development point of view the definition allows you to tell the API about your cache, what it requires, and any (if any) advanced features you want it to have. 
The following shows a basic definition containing just the bare minimum:
<code php>
// moodle/mod/myplugin/db/caches.php
$definitions = [
'somedata' => [
'mode' => cache_store::MODE_APPLICATION
]
];
</code>
This informs the API that the myplugin module has a cache called ''somedata'' and that it is an application (globally shared) cache. 
When creating a definition thats the bare minimum, to provide an area ''(somedata)'' and declare the type of the cache application, session, or request. 
:An application cache is a shared cache, all users can access it. 
:Session caches are, well, just stores in the users session. 
:Request caches you can think of as static caches, only available to the user owning the request, and only alive until the end of the request. 
There are of course many more options available that allow you to really take the cache by the reigns, you can read about some of the important ones further on, or skip ahead to [[#The definition]] section which details the available options in full.

Please note that for each definition a language string with the name ''cachedef_'' followed by the name of the definition is expected. Using the example above you would have to define:

<code php>
// moodle/mod/myplugin/lang/en/mod_myplugin.php
$string['cachedef_somedata'] = 'This is the description of the cache somedata';
</code>

===Getting a cache object===
Once your definition has been created you should bump the version number so that Moodle upgrades and processes the definitions file at which point your definition will be useable.

Now within code you can get a cache object corresponding to the definition created earlier.

<code php>
$cache = cache::make('mod_myplugin', 'somedata');
</code>

The cache::make method is a factory method, it will create a cache object to allow you to work with your cache. The cache object will be one of several classes chosen by the API based upon what your definition contains. All of these classes will extend the base cache class, and in nearly all cases you will get one of cache_application, cache_session, or cache_request depending upon the mode you selected.

===Using your cache object===
Once you have a cache object (will extend the cache class and implements cache_loader) you are ready to start interacting with the cache.

Of course there are three basic basic operations. get, set, and delete.

The first is to send something to the cache.
<code php>
$result = $cache->set('key', 'value');
</code>
Easy enough. The key must be an int or a string. The value can be absolutely anything your want that is [https://www.php.net/manual/en/function.serialize.php serializable].
The result is true if the operation was a success, false otherwise.

The second is to fetch something from the cache.
<code php>
$data = $cache->get('key');
</code>
$data will either be whatever was being stored in the cache, or false if the cache could not find the key.

The third and final operation is delete.
<code php>
$result = $cache->delete('key');
</code>
Again just like set the result will either be true if the operation was a success, or false otherwise.

You can also set, get, and delete multiple key=>value pairs in a single transaction.
<code php>
$result = $cache->set_many([
'key1' => 'data1',
'key3' => 'data3'
]);
// $result will be the number of pairs sucessfully set.

$result = $cache->get_many(['key1', 'key2', 'key3']);
print_r($result);
// Will print the following:
// array(
// 'key1' => 'data1',
// 'key2' => false,
// 'key3' => 'data3'
// )

$result = $cache->delete_many(['key1', 'key3']);
// $result will be the number of records sucessfully deleted.
</code>

That covers the basic operation of the Cache API. 
In many situations there is not going to be any more to it than that.

==Ad-hoc Caches==
This is the alternative method of using the cache API. 
It involves creating a cache using just the required params at the time that it is required. It doesn't require that a definition exists making it quicker and easier to use, however it can only use the default settings and is only recommended for insignificant caches (rarely used during operation, never to be mapped or customised, only existsing in a single place in code).

Once a cache object has been retrieved it operates exactly as the same as a cache that has been created for a definition.

To create an ad-hoc cache you would use the following:
<code php>
$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_myplugin', 'mycache');
</code>

Really don't be lazy, if you don't have a good reason to use an ad-hoc cache you should be spending a extra 5 minutes creating a definition.

==The definition==

The above section illustrated how to create a basic definition, specifying just the area name (the key) and the mode for the definition. Those being the two required properties for a definition. 
There are many other options that will let you make the most of the Cache API and will undoubtedly be required when implementing and converting cache solutions to the Cache API.

The following details the options available to a definition and their defaults if not applied:

<code php>
$definitions = [
// The name of the cache area is the key. The component/plugin will be picked up from the file location.
'area' => [
'mode' => cache_store::MODE_*,
'simplekeys' => false,
'simpledata' => false,
'requireidentifiers' => ['ident1', 'ident2'],
'requiredataguarantee' => false,
'requiremultipleidentifiers' => false,
'requirelockingread' => false,
'requirelockingwrite' => false,
'maxsize' => null,
'overrideclass' => null,
'overrideclassfile' => null,
'datasource' => null,
'datasourcefile' => null,
'staticacceleration' => false,
'staticaccelerationsize' => null,
'ttl' => 0,
'mappingsonly' => false,
'invalidationevents' => ['event1', 'event2'],
'canuselocalstore' => false
'sharingoptions' => cache_definition::SHARING_DEFAULT,
'defaultsharing' => cache_definition::SHARING_DEFAULT,
],
];
</code>

===Setting requirements===
The definition can specify several requirements for the cache. 
This includes identifiers that must be provided when creating the cache object, that the store guarantees data stored in it will remain there until removed, a store that supports multiple identifiers, and finally read/write locking.
The options for these are as follows:

; simplekeys : [bool] Set to true if your cache will only use simple keys for its items. Simple keys consist of digits, underscores and the 26 chars of the english language. a-zA-Z0-9_ If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes. It will be better for performance and possible only because we know the keys are safe.
; simpledata : [bool] If set to true we know that the data is scalar or array of scalar.
; requireidentifiers : [array] An array of identifiers that must be provided to the cache when it is created.
; requiredataguarantee : [bool] If set to true then only stores that can guarantee data will remain available once set will be used.
; requiremultipleidentifiers : [bool] If set to true then only stores that support multiple identifiers will be used.
; requirelockingread : [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required. Remember 99.9% of caches will NOT need this setting. This setting will only be used for application caches presently.
; requirelockingwrite : [bool] If set to true then a lock will be gained before writing to the cache store. As above this is not recommended unless truly needed. Please think about the order of your code and deal with race conditions there first. This setting will only be used for application caches presently.

===Cache modifiers===
You are also to modify the way in which the cache is going to operate when working for your definition. 
By enabling the static option the Cache API will only ever generate a single cache object for your definition on the first request for it, further requests will be returned the original instance. This greatly speeds up the collecting of a cache object. 
Enabling persistence also enables a static store within the cache object, anything set to the cache, or retrieved from it will be stored in that static array for the life of the request.
This makes the persistence options some of the most powerful. If you know you are going to be using you cache over and over again or if you know you will be making lots of requests for the same items then this will provide a great performance boost.
Of course the static storage of cache objects and of data is costly in terms of memory and should only be used when actually required, as such it is turned off by default.
As well as persistence you can also set a maximum number of items that the cache should store (not a hard limit, its up to each store) and a time to live (ttl) although both are discouraged as efficient design negates the need for both in most situations.

; staticacceleration : [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for this definition once, further requests will be given the original instance. Second the cache loader will keep an array of the items set and retrieved to the cache during the request. This has several advantages including better performance without needing to start passing the cache instance between function calls, the downside is that the cache instance + the items used stay within memory. Consider using this setting when you know that there are going to be many calls to the cache for the same information or when you are converting existing code to the cache and need to access the cache within functions but don't want to add it as an argument to the function.
; staticaccelerationsize : [int] This supplements the above setting by limiting the number of items in the caches persistent array of items. Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store.
; ttl : [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system (even if the event is just time expiring, better not to rely on ttl). Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not.
; maxsize : [int] If set this will be used as the maximum number of entries within the cache store for this definition. Its important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit.
; canuselocalstore : [bool] This setting specifies whether the cache can safely be local to each frontend in a cluster which can avoid latency costs to a shared central cache server. The cache needs to be carefully written for this to be safe. It is conceptually similar to using $CFG->localcachedir (can be local) vs $CFG->cachedir (must be shared). Look at purify_html() in lib/weblib.php for an example.

===Overriding a cache loader===

This is a super advanced feature and should not be done. ever. Unless you have an very good reason to do so.
It allows you to create your own cache loader and have it be used instead of the default cache loader class. The cache object you get back from the make operations will be an instance of this class.

; overrideclass : [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution. Any class used here must inherit the cache_loader interface and must extend default cache loader for the mode they are using.
; overrideclassfile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.

===Specifying a data source===

This is a great wee feature, especially if your code is object orientated.

It allows you to specify a class that must inherit the cache_data_source object and will be used to load any information requested from the cache that is not already being stored.

When the requested key cannot be found in the cache the data source will be asked to load it. The data source will then return the information to the cache, the cache will store it, and it will then return it to the user as a request of their get request. Essentially no get request should ever fail if you have a data source specified.

; datasource : [string] A class to use as the data loader for this definition. Any class used here must inherit the cache_data_source interface.
; datasourcefile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.

GOTCHA: Note that if caching is disabled then *nothing* will be loaded through the data source which is probably not what you expect (rather than the data source being loaded every time but never cached). See also:

https://tracker.moodle.org/browse/MDL-42012

===Misc settings===
The following are stand along settings that don't fall into any of the above categories.

; invalidationevents : [array] An array of events that should cause this cache to invalidate some or all of the items within it.
; mappingsonly : [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another.
; sharingoptions : [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options.
; defaultsharing : [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default.

==The loader==

== Localized stores for distributed high performance caching ==

Most cache definitions are simple in that the code expects to be able to purge the cache, or update it, and for this to be universally available from then on to all code which loads from this cache again. But as you scale up having a single mega shared cache store doesn't work well for a variety of reasons, including extra latency between multiple front ends and the shared cache service, the number of connections the cache server can handle, the cost of IO between services, and depending on the cache definition issues with locking while writing.

So if you want very high performance caching then you need to write you code so that it can support being distributed, or localized, which means that each front end can have it's own independent cache store. But this architecture means that you have no direct way to communicate from code running in one place to invalidate the caches on all the other front ends. In order to achieve this you need to carefully construct cache keys so that if the content changes then it uses a new cache key, which will of course be a cache miss and then it will regenerate using fresh data. There are multiple ways to achieve this, a couple common example strategies are below.

=== Revision numbers as key suffix ===

A simple method is storing a version number somewhere and appending that to your key. This is the most common method used in Moodle, simply store a number somewhere which is globally shared such as in a custom db field, or using set_config / get_config.

One small edge case with this approach is you now need to make sure that the incrementing code is atomic, which means you should use a DB transaction, or gain a lock, before bumping the version so you don't get two conflicting changes ending up on the same version with a race condition. However if you are anticipating high turnover rate of the cache you probably have a deeper issue, see 'Fast churning keys' below.

One potential benefit of a simple version number strategy if your cache misses are very expensive, is that you can check for the presence of a version, and if it doesn't exist it is easy to simply retrieve the previous version and use it in the mean time, while you could generate the new version asynchronously. This is an advanced concept and depends on the use case and has the obvious disadvantage of showing stale data.

And example of this stragegy in Moodle is the modinfo cache.

=== Using time as a key suffix ===

Another common approach is to use a timestamp, this is how some of the core cache numbers work, see increment_revision_number() for some examples. This has the benefit of not needing any transaction or locking, but you do run the risk of two processes clashing if they happen to run in the same second, so generally don't do this.

It may look like Moodle theme-related caching uses this strategry, but actually if you look at [https://github.com/moodle/moodle/blob/df0e58adb140f90712bcd3229ad936d3b4bc15d9/lib/outputlib.php#L88 the code for theme_get_next_revision], you will see that it is actually guaranteeing to generate a unique new integer. It is just making that integer close to current time-stamp, to make it more self-documenting.

https://github.com/moodle/moodle/blob/master/lib/datalib.php#L1131-L1145

=== Content hashes as keys ===

A great strategy is to use a hash such as sha1 / sha256 of the content stored inside the cache, or in even more advanced scenarios a hash of the dependencies of the content in the cache. This guarantees that the key will be unique, and can be truly distributed without any synchronous communication between the front ends.

This strategy can work very well when building up large cache items from many smaller cache fragments in a nested tree structure, eg when caching a structure which is built of other cache items, eg 10 chunks of html to get combined into a large chunk to be cached, you would append the 10 hashes of the 10 smaller chunks and then hash that to use as the key for the combined cache item. This means you can mutate a small part of a tree structure and quickly re-generate the whole tree without expensively regenerating all of the other branches and leaves in the tree.

This is known as 'Russian Doll' caching:

https://blog.appsignal.com/2018/04/03/russian-doll-caching-in-rails.html

This is a very common strategy is many distributed systems, outside of the context of caching, and is conceptually how git works internally.

=== Primary and Final caches ===

Because http requests are generally assigned randomly or round-robin to front ends, when a cache item version changes you will now effectively have an empty cache on every front end. As you get the same cache item again and again on each front end it will continue to be a cache miss on each local box until they are all warm, which can ironically mean that on average for a fast changing, but not often requested cache item, your cache hit rate will be very low and much worse than if you had a shared cache. The solution here is to have multiple levels of caches setup, a local cache backed by a shared cache. You do not need to do anything special in the code to support this, the MUC manages this for you, ie if you request a key is missing from the local cache it will then request it from the shared cache. If present it will copy it back to the local cache. If it is not present in either then your fall back code will generate the item, and it will be written to both cache stores at the same time.

This is especially important if you are scaling up and down the number of frontends quickly. If you suddenly need more horizontal scale and create a bunch of new front ends with empty caches and no shared cache they will all consume even more resources warming up and loading the shared services such as the database and filesystem.

A good rule of thumb is to pair similar types of local and shared caches together. For instance it is very common to store the Moodle string cache in APCu because it is very heavily used, so an in-memory cache is the fastest and is well paired this a shared cache like Redis. coursemodinfo on the other hand is often very large so isn't as practical to store in Redis so it is usually cached on disk, so you could have a local file cache (which could often be very fast SSD) and pair it with a shared disk cache in dataroot (often much slower over NFS or Gluster etc).

=== Beware fast churning keys ===

A big concern when designing a cache is how fast you anticipate it to change. If it contains very fast moving data but sparsely requested data (see above) then you can end up in a situation where you are effectively just using the shared final cache, and wasting latency and space and IO cloning data to the local cache where is may not be hit again very much. As always caching is a balancing act trading off between CPU, time and disk, and ultimately money.

Even if you cache is able to use a local store that doesn't mean it actually will be configured to be local (and you can't tell either way). So a wasteful cache item will consume much more space storing all the previous versions of its items even if it isn't localized, and it will be much worse if it is.

=== Time to life for distributed caches ===

Another consideration is the total size of your cache stores across all the front ends. As cache keys change they are never invalidated or purged. So you should have in place some process to garbage collect stale items. This is more a concern for the cache store implementations and the configuration but worth considering. Some stores are deleted on upgrade, or have a Time-To-Live or a Least Recently Used strategy for deleting stale items.

==Using a data source==

==Developing cache plugins==

==Miscellaneous==
* Checkout important [https://moodle.org/local/chatlogs/index.php?q=cache discussion about the Cache API at the Moodle developer (Telegram) chat]

Cache API

2020-04-16T11:57:59Z

Tim Hunt: /* Revision numbers as key suffix */

This document details the Cache API aka MUC aka Moodle's Universal Cache.
I've chosen to use a tutorial/example flow for this document always working with a theoretical module plugin called myplugin.
There is also a [[Cache API - Quick reference]] if you would rather read that.

==Basic usage==
It's very easy to get started with the Cache API. It is designed to be as easy and as quick to use as possible and is predominantely self contained.
All you need to do is add a definition for your cache and you are ready to start working with the Cache API.

===Creating a definition===
Cache definitions exist within the db/caches.php file for a component/plugin. 
In the case of core that is the moodle/lib/db/caches.php file, in the case of a module that would be moodle/mod/myplugin/db/caches.php.

The definition is used API in order to understand a little about the cache and what it is being used for, it also allows the administrator to set things up especially for the definition if they want.
From a development point of view the definition allows you to tell the API about your cache, what it requires, and any (if any) advanced features you want it to have. 
The following shows a basic definition containing just the bare minimum:
<code php>
// moodle/mod/myplugin/db/caches.php
$definitions = [
'somedata' => [
'mode' => cache_store::MODE_APPLICATION
]
];
</code>
This informs the API that the myplugin module has a cache called ''somedata'' and that it is an application (globally shared) cache. 
When creating a definition thats the bare minimum, to provide an area ''(somedata)'' and declare the type of the cache application, session, or request. 
:An application cache is a shared cache, all users can access it. 
:Session caches are, well, just stores in the users session. 
:Request caches you can think of as static caches, only available to the user owning the request, and only alive until the end of the request. 
There are of course many more options available that allow you to really take the cache by the reigns, you can read about some of the important ones further on, or skip ahead to [[#The definition]] section which details the available options in full.

Please note that for each definition a language string with the name ''cachedef_'' followed by the name of the definition is expected. Using the example above you would have to define:

<code php>
// moodle/mod/myplugin/lang/en/mod_myplugin.php
$string['cachedef_somedata'] = 'This is the description of the cache somedata';
</code>

===Getting a cache object===
Once your definition has been created you should bump the version number so that Moodle upgrades and processes the definitions file at which point your definition will be useable.

Now within code you can get a cache object corresponding to the definition created earlier.

<code php>
$cache = cache::make('mod_myplugin', 'somedata');
</code>

The cache::make method is a factory method, it will create a cache object to allow you to work with your cache. The cache object will be one of several classes chosen by the API based upon what your definition contains. All of these classes will extend the base cache class, and in nearly all cases you will get one of cache_application, cache_session, or cache_request depending upon the mode you selected.

===Using your cache object===
Once you have a cache object (will extend the cache class and implements cache_loader) you are ready to start interacting with the cache.

Of course there are three basic basic operations. get, set, and delete.

The first is to send something to the cache.
<code php>
$result = $cache->set('key', 'value');
</code>
Easy enough. The key must be an int or a string. The value can be absolutely anything your want that is [https://www.php.net/manual/en/function.serialize.php serializable].
The result is true if the operation was a success, false otherwise.

The second is to fetch something from the cache.
<code php>
$data = $cache->get('key');
</code>
$data will either be whatever was being stored in the cache, or false if the cache could not find the key.

The third and final operation is delete.
<code php>
$result = $cache->delete('key');
</code>
Again just like set the result will either be true if the operation was a success, or false otherwise.

You can also set, get, and delete multiple key=>value pairs in a single transaction.
<code php>
$result = $cache->set_many([
'key1' => 'data1',
'key3' => 'data3'
]);
// $result will be the number of pairs sucessfully set.

$result = $cache->get_many(['key1', 'key2', 'key3']);
print_r($result);
// Will print the following:
// array(
// 'key1' => 'data1',
// 'key2' => false,
// 'key3' => 'data3'
// )

$result = $cache->delete_many(['key1', 'key3']);
// $result will be the number of records sucessfully deleted.
</code>

That covers the basic operation of the Cache API. 
In many situations there is not going to be any more to it than that.

==Ad-hoc Caches==
This is the alternative method of using the cache API. 
It involves creating a cache using just the required params at the time that it is required. It doesn't require that a definition exists making it quicker and easier to use, however it can only use the default settings and is only recommended for insignificant caches (rarely used during operation, never to be mapped or customised, only existsing in a single place in code).

Once a cache object has been retrieved it operates exactly as the same as a cache that has been created for a definition.

To create an ad-hoc cache you would use the following:
<code php>
$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_myplugin', 'mycache');
</code>

Really don't be lazy, if you don't have a good reason to use an ad-hoc cache you should be spending a extra 5 minutes creating a definition.

==The definition==

The above section illustrated how to create a basic definition, specifying just the area name (the key) and the mode for the definition. Those being the two required properties for a definition. 
There are many other options that will let you make the most of the Cache API and will undoubtedly be required when implementing and converting cache solutions to the Cache API.

The following details the options available to a definition and their defaults if not applied:

<code php>
$definitions = [
// The name of the cache area is the key. The component/plugin will be picked up from the file location.
'area' => [
'mode' => cache_store::MODE_*,
'simplekeys' => false,
'simpledata' => false,
'requireidentifiers' => ['ident1', 'ident2'],
'requiredataguarantee' => false,
'requiremultipleidentifiers' => false,
'requirelockingread' => false,
'requirelockingwrite' => false,
'maxsize' => null,
'overrideclass' => null,
'overrideclassfile' => null,
'datasource' => null,
'datasourcefile' => null,
'staticacceleration' => false,
'staticaccelerationsize' => null,
'ttl' => 0,
'mappingsonly' => false,
'invalidationevents' => ['event1', 'event2'],
'canuselocalstore' => false
'sharingoptions' => cache_definition::SHARING_DEFAULT,
'defaultsharing' => cache_definition::SHARING_DEFAULT,
],
];
</code>

===Setting requirements===
The definition can specify several requirements for the cache. 
This includes identifiers that must be provided when creating the cache object, that the store guarantees data stored in it will remain there until removed, a store that supports multiple identifiers, and finally read/write locking.
The options for these are as follows:

; simplekeys : [bool] Set to true if your cache will only use simple keys for its items. Simple keys consist of digits, underscores and the 26 chars of the english language. a-zA-Z0-9_ If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes. It will be better for performance and possible only because we know the keys are safe.
; simpledata : [bool] If set to true we know that the data is scalar or array of scalar.
; requireidentifiers : [array] An array of identifiers that must be provided to the cache when it is created.
; requiredataguarantee : [bool] If set to true then only stores that can guarantee data will remain available once set will be used.
; requiremultipleidentifiers : [bool] If set to true then only stores that support multiple identifiers will be used.
; requirelockingread : [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required. Remember 99.9% of caches will NOT need this setting. This setting will only be used for application caches presently.
; requirelockingwrite : [bool] If set to true then a lock will be gained before writing to the cache store. As above this is not recommended unless truly needed. Please think about the order of your code and deal with race conditions there first. This setting will only be used for application caches presently.

===Cache modifiers===
You are also to modify the way in which the cache is going to operate when working for your definition. 
By enabling the static option the Cache API will only ever generate a single cache object for your definition on the first request for it, further requests will be returned the original instance. This greatly speeds up the collecting of a cache object. 
Enabling persistence also enables a static store within the cache object, anything set to the cache, or retrieved from it will be stored in that static array for the life of the request.
This makes the persistence options some of the most powerful. If you know you are going to be using you cache over and over again or if you know you will be making lots of requests for the same items then this will provide a great performance boost.
Of course the static storage of cache objects and of data is costly in terms of memory and should only be used when actually required, as such it is turned off by default.
As well as persistence you can also set a maximum number of items that the cache should store (not a hard limit, its up to each store) and a time to live (ttl) although both are discouraged as efficient design negates the need for both in most situations.

; staticacceleration : [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for this definition once, further requests will be given the original instance. Second the cache loader will keep an array of the items set and retrieved to the cache during the request. This has several advantages including better performance without needing to start passing the cache instance between function calls, the downside is that the cache instance + the items used stay within memory. Consider using this setting when you know that there are going to be many calls to the cache for the same information or when you are converting existing code to the cache and need to access the cache within functions but don't want to add it as an argument to the function.
; staticaccelerationsize : [int] This supplements the above setting by limiting the number of items in the caches persistent array of items. Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store.
; ttl : [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system (even if the event is just time expiring, better not to rely on ttl). Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not.
; maxsize : [int] If set this will be used as the maximum number of entries within the cache store for this definition. Its important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit.
; canuselocalstore : [bool] This setting specifies whether the cache can safely be local to each frontend in a cluster which can avoid latency costs to a shared central cache server. The cache needs to be carefully written for this to be safe. It is conceptually similar to using $CFG->localcachedir (can be local) vs $CFG->cachedir (must be shared). Look at purify_html() in lib/weblib.php for an example.

===Overriding a cache loader===

This is a super advanced feature and should not be done. ever. Unless you have an very good reason to do so.
It allows you to create your own cache loader and have it be used instead of the default cache loader class. The cache object you get back from the make operations will be an instance of this class.

; overrideclass : [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution. Any class used here must inherit the cache_loader interface and must extend default cache loader for the mode they are using.
; overrideclassfile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.

===Specifying a data source===

This is a great wee feature, especially if your code is object orientated.

It allows you to specify a class that must inherit the cache_data_source object and will be used to load any information requested from the cache that is not already being stored.

When the requested key cannot be found in the cache the data source will be asked to load it. The data source will then return the information to the cache, the cache will store it, and it will then return it to the user as a request of their get request. Essentially no get request should ever fail if you have a data source specified.

; datasource : [string] A class to use as the data loader for this definition. Any class used here must inherit the cache_data_source interface.
; datasourcefile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.

GOTCHA: Note that if caching is disabled then *nothing* will be loaded through the data source which is probably not what you expect (rather than the data source being loaded every time but never cached). See also:

https://tracker.moodle.org/browse/MDL-42012

===Misc settings===
The following are stand along settings that don't fall into any of the above categories.

; invalidationevents : [array] An array of events that should cause this cache to invalidate some or all of the items within it.
; mappingsonly : [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another.
; sharingoptions : [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options.
; defaultsharing : [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default.

==The loader==

== Localized stores for distributed high performance caching ==

Most cache definitions are simple in that the code expects to be able to purge the cache, or update it, and for this to be universally available from then on to all code which loads from this cache again. But as you scale up having a single mega shared cache store doesn't work well for a variety of reasons, including extra latency between multiple front ends and the shared cache service, the number of connections the cache server can handle, the cost of IO between services, and depending on the cache definition issues with locking while writing.

So if you want very high performance caching then you need to write you code so that it can support being distributed, or localized, which means that each front end can have it's own independent cache store. But this architecture means that you have no direct way to communicate from code running in one place to invalidate the caches on all the other front ends. In order to achieve this you need to carefully construct cache keys so that if the content changes then it uses a new cache key, which will of course be a cache miss and then it will regenerate using fresh data. There are multiple ways to achieve this, a couple common example strategies are below.

=== Revision numbers as key suffix ===

A simple method is storing a version number somewhere and appending that to your key. This is the most common method used in Moodle, simply store a number somewhere which is globally shared such as in a custom db field, or using set_config / get_config.

One small edge case with this approach is you now need to make sure that the incrementing code is atomic, which means you should use a DB transaction, or gain a lock, before bumping the version so you don't get two conflicting changes ending up on the same version with a race condition. However if you are anticipating high turnover rate of the cache you probably have a deeper issue, see 'Fast churning keys' below.

One potential benefit of a simple version number strategy if your cache misses are very expensive, is that you can check for the presence of a version, and if it doesn't exist it is easy to simply retrieve the previous version and use it in the mean time, while you could generate the new version asynchronously. This is an advanced concept and depends on the use case and has the obvious disadvantage of showing stale data.

And example of this stragegy in Moodle is the modinfo cache.

=== Using time as a key suffix ===

Another common approach is to use a timestamp, this is how some of the core cache numbers work, see increment_revision_number() for some examples. This has the benefit of not needing any transaction or locking, but you do run the risk of two processes clashing if they happen to run in the same second. For many common use cases such as theme caches and js compilation caches this is not a risk.

=== Content hashes as keys ===

A great strategy is to use a hash such as sha1 / sha256 of the content stored inside the cache, or in even more advanced scenarios a hash of the dependencies of the content in the cache. This guarantees that the key will be unique, and can be truly distributed without any synchronous communication between the front ends.

This strategy can work very well when building up large cache items from many smaller cache fragments in a nested tree structure, eg when caching a structure which is built of other cache items, eg 10 chunks of html to get combined into a large chunk to be cached, you would append the 10 hashes of the 10 smaller chunks and then hash that to use as the key for the combined cache item. This means you can mutate a small part of a tree structure and quickly re-generate the whole tree without expensively regenerating all of the other branches and leaves in the tree.

This is known as 'Russian Doll' caching:

https://blog.appsignal.com/2018/04/03/russian-doll-caching-in-rails.html

This is a very common strategy is many distributed systems, outside of the context of caching, and is conceptually how git works internally.

=== Primary and Final caches ===

Because http requests are generally assigned randomly or round-robin to front ends, when a cache item version changes you will now effectively have an empty cache on every front end. As you get the same cache item again and again on each front end it will continue to be a cache miss on each local box until they are all warm, which can ironically mean that on average for a fast changing, but not often requested cache item, your cache hit rate will be very low and much worse than if you had a shared cache. The solution here is to have multiple levels of caches setup, a local cache backed by a shared cache. You do not need to do anything special in the code to support this, the MUC manages this for you, ie if you request a key is missing from the local cache it will then request it from the shared cache. If present it will copy it back to the local cache. If it is not present in either then your fall back code will generate the item, and it will be written to both cache stores at the same time.

This is especially important if you are scaling up and down the number of frontends quickly. If you suddenly need more horizontal scale and create a bunch of new front ends with empty caches and no shared cache they will all consume even more resources warming up and loading the shared services such as the database and filesystem.

A good rule of thumb is to pair similar types of local and shared caches together. For instance it is very common to store the Moodle string cache in APCu because it is very heavily used, so an in-memory cache is the fastest and is well paired this a shared cache like Redis. coursemodinfo on the other hand is often very large so isn't as practical to store in Redis so it is usually cached on disk, so you could have a local file cache (which could often be very fast SSD) and pair it with a shared disk cache in dataroot (often much slower over NFS or Gluster etc).

=== Beware fast churning keys ===

A big concern when designing a cache is how fast you anticipate it to change. If it contains very fast moving data but sparsely requested data (see above) then you can end up in a situation where you are effectively just using the shared final cache, and wasting latency and space and IO cloning data to the local cache where is may not be hit again very much. As always caching is a balancing act trading off between CPU, time and disk, and ultimately money.

Even if you cache is able to use a local store that doesn't mean it actually will be configured to be local (and you can't tell either way). So a wasteful cache item will consume much more space storing all the previous versions of its items even if it isn't localized, and it will be much worse if it is.

=== Time to life for distributed caches ===

Another consideration is the total size of your cache stores across all the front ends. As cache keys change they are never invalidated or purged. So you should have in place some process to garbage collect stale items. This is more a concern for the cache store implementations and the configuration but worth considering. Some stores are deleted on upgrade, or have a Time-To-Live or a Least Recently Used strategy for deleting stale items.

==Using a data source==

==Developing cache plugins==

==Miscellaneous==
* Checkout important [https://moodle.org/local/chatlogs/index.php?q=cache discussion about the Cache API at the Moodle developer (Telegram) chat]

Running acceptance test

2020-04-07T12:22:51Z

Tim Hunt: /* 2. Set up Selenium */

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====
First, you should have a look at [[Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium#Working_combinations_of_OS.2BBrowser.2Bselenium|working combinations of OS+Browser+selenium]].

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/]. Ensure you have the right version of the Chrome driver - see [[#Trouble_shooting| Trouble shooting]]. (Firefox is currently problematic. See [[Actual_Selenium_with_old_Firefox_47.0.1]] if you need to try to make it work.)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j=<number> or --parallel=<number>''' (required) Number of parallel behat run to initialise
# '''-m=<number> or --maxruns=<number>''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun=<number>''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun=<number>''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a=<name> or --add-core-features-to-theme=<name>''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

You almost always want to limit the number of tests that are run. To run all the tests in one plugin:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin
</code>

To run all the tests in one .feature file:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature
</code>

To run a single scenario:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature:40
</code>

Here, '40' is the line-number of the feature file where the Scenario starts.

=== Parallel runs ===
For running parallel runs, use following command

php admin/tool/behat/cli/run.php

Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

Example: Initialise and run Behat tests for a custom plugin under a custom theme:

php admin/tool/behat/cli/init.php --parallel=3 --add-core-features-to-theme="mytheme"
php admin/tool/behat/cli/run.php --tags="@tool_myplugin" --suite="mytheme"

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" iframe''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with --add-core-features-to-theme={THEME_NAME}, e.g.

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===

If you follow the steps above, Behat will run with Chrome.

You can get it to run with other browsers. The basic idea is to expand the $CFG->behat_profiles array in config.php to list more browsers.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>

[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== Trouble shooting ==

=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===

If you followed all the steps and you receive an unknown weird error probably your browser version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== Errors during setup (before test are launched) ===
Typical errors are:
* Behat requirement not satisfied: http://127.0.0.1/m/stable_master is not available, ensure you specified correct url and that the server is set up and started.
* Behat is configured but not enabled on this test site.

In order to fix those errors please check that: the behat_dataroot has correct write permissions and that the $CFG->behat* variables are placed before the lib/setup.php include:
require_once(__DIR__ . '/lib/setup.php');

=== Selenium server is not running ===
==== Chrome specific ====

If you are using chrome, you need to ensure that the driver matches the version of the installed chrome browser – which may change on OS updates/upgrades. Moodle or Selenium will not give the appropriate message – see [https://tracker.moodle.org/browse/MDL-67659/ MDL-67659]. One solution is the one suggested in the issue and use Andrew Nicols’ [https://github.com/andrewnicols/chromedriver-wrapper/ Chromedriver Wrapper] which will ensure you have the appropriate driver before running the tests.

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

== See also ==
* [[Acceptance testing for the mobile app]]

[[Category:Quality Assurance]][[Category:Behat]]

Running acceptance test

2020-04-07T12:19:30Z

Tim Hunt: /* 2. Set up Selenium */

== Short version ==

...or how I got it to work on Ubuntu and some of the problems encountered.

You need a bunch of browsers and terminal windows open to do this.

==== 1. Background ====

# I am using the desktop version of Ubuntu 17.04 so there are no issues about running this software in headless mode. Running in headless mode was not tested.
# Moodle is version 3.3 and is a fully installed and working version using the 'standard' Ubuntu LAMP stack.

==== 2. Set up Selenium ====
First, you should have a look at [[Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium#Working_combinations_of_OS.2BBrowser.2Bselenium|working combinations of OS+Browser+selenium]].

# Download the Selenium Standalone Server from [http://www.seleniumhq.org/download/ http://www.seleniumhq.org/download/]. It's a single JAR file, put it anywhere handy.
# Download the Chrome driver from [https://sites.google.com/a/chromium.org/chromedriver/ https://sites.google.com/a/chromium.org/chromedriver/]. Ensure you have the right version of the Chrome driver - see [[#Trouble_shooting| Trouble shooting]]. (Firefox is currently problematic. See [[Actual_Selenium_with_old_Firefox_47.0.1]] if you need to try to make it work.)
# Unzip the driver (it's a single file) and copy to /usr/local/bin (should work anywhere on the path)
# If not installed already, '<tt>sudo apt install default-jre</tt>'
# Start Selenium - '<tt>java -jar /path/to/your/selenium/server/selenium-server-standalone-N.NN.N.jar -port 4444</tt>'
# check it works, access 'localhost:4444/wd/hub/' in your browser and check you can create a new Chrome session.

If running headless or the above doesn't work ("Selenium server is not running" when running the behat tests). Try the following
# Run '<tt>Xvfb -ac :99 -screen 0 1280x1024x16 &</tt>'
# Then immediately, '<tt>export DISPLAY=:99</tt>'
# The run the Selenium command as above

==== 3. Set up Moodle ====

# Create a new 'dataroot' area for files especially for behat adjusting permissions accordingly.
# If not there already, add Section 11 from config-dist.php to your config.php file and review the settings.
# $CFG->behat_wwwroot needs to point to your Moodle site yet be different from the 'normal' wwwroot (e.g. if you used localhost for wwwroot use 127.0.0.1 for the behat_wwwroot). Whatever you choose, make sure it works.
# $CFG->behat_dataroot should point to the directory you created above
# $CFG->behat_prefix should be fine.
# Set up $CFG->behat_profiles to select Chrome as the browser...

$CFG->behat_profiles = [
'default' => [
'browser' => 'chrome',
'extensions' => [
'Behat\MinkExtension' => [
'selenium2' => [
'browser' => 'chrome',
]
]
]
]
];

==== 4. Configure Behat for Moodle ====

# Run '<tt>php admin/tool/behat/cli/init.php</tt>' (from the root of your Moodle install). This installs all the required software and creates the test version of Moodle.

==== 5. Run Behat tests ====

# Run '<tt>vendor/bin/behat</tt>'. If you don't want to run all the tests add '<tt>--tags="@something"</tt>' where the @something refers to the tags at the top of most feature files. Use comma-separated list like '<tt>@some_thing,@some_thing_else</tt>' to run tests from multiple areas. See upstream documentation on Gherkin filters for advanced syntax and more complex examples.
# After some initial setup dots should start to go by. It's a while before Selenium is first accessed. On the Linux desktop a new Chrome window appears and the testing process 'remote control' starts (hopefully!)

== Prerequisite ==
Before initializing acceptance test environment for running behat, you should ensure:
# [[Acceptance_testing#Requirements Meet min. system requirements for running tests]]
# [[Acceptance_testing#Installation Have set min. config variable in config.php for behat]]
# [[Acceptance_testing#Installation Downloaded composer dependencies]]

== Overview ==
Acceptance tests (also known as behat), use [http://www.seleniumhq.org/download/ Selenium server] and can be run as:
# '''Single run:''' In single run, only one behat run is executed. So all features are executed in this single run.
# '''Parallel runs:''' (Since Moodle 3.0) Parallel runs allow dev's to execute multiple behat runs together. This was introduced to get acceptance tests results faster. To achieve this:
#* Features are divided between multiple behat runs
#* Symlinks behatrun{x} (x being the run process number), are created pointing to moodle directory, so site for run 1 is accessible via https://localhost/moodle/behatrun1
#* Process number is included as suffix to $CFG->behat_prefix.
#* Process number is suffixed to $CFG->behat_dataroot.

== Step 1: Initialise acceptance test environment ==
Before running acceptance tests, environment needs to be initialised for acceptance testing.

=== Single run ===
For initialising acceptance tests for single run, above command is sufficient.
<code>
php admin/tool/behat/cli/init.php
</code>

=== Parallel runs ===
For initialising acceptance tests for parallel runs, you can use one of the following options
# '''-j=<number> or --parallel=<number>''' (required) Number of parallel behat run to initialise
# '''-m=<number> or --maxruns=<number>''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun=<number>''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun=<number>''' (optional) Initialise site to run specified run till. Used for running acceptance tests on different vms
# '''-o or --optimize-runs''' (optional) This option will split features with specified tags in all parallel runs, so they are executed first when parallel run gets executed.
# '''-a=<name> or --add-core-features-to-theme=<name>''' (optional) Since Moodle 3.2. Use this option to add all core features to specified themes (comma separated list of themes)
<code>
// Below command will initialise moodle to run 2 parallel tests.
php admin/tool/behat/cli/init.php --parallel=2
</code>

== Step 2: Running acceptance test environment ==
=== Single run ===
Run either of the following commands. For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html
<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml
</code>

You almost always want to limit the number of tests that are run. To run all the tests in one plugin:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin
</code>

To run all the tests in one .feature file:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature
</code>

To run a single scenario:

<code>
vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml /path/to/moodle/mod/myplugin/tests/behat/testsomething.feature:40
</code>

Here, '40' is the line-number of the feature file where the Scenario starts.

=== Parallel runs ===
For running parallel runs, use following command

php admin/tool/behat/cli/run.php

Following optional options are available for custom run:
# '''--feature''' Only execute specified feature file (Absolute path of feature file).
# '''--suite''' Features for specified theme will be executed.
# '''--replace''' Replace args string with run process number, useful for output and reruns.
# '''--fromrun''' Execute run starting from (Used for parallel runs on different vms)
# '''--torun''' Execute run till (Used for parallel runs on different vms)
# Behat options can be passed for filtering features/scenarios:
#* In case you don't want to run Javascript tests, use the Behat tags option to skip them, '''--tags="~@javascript"'''
#* In case you want to run specific scenario, use the Behat name option to run it, '''--name="Filter user accounts by role and cohort"'''
#* In case you want to run specific feature file, use the Behat feature option to run it, '''--feature="/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature"'''

Example: Initialise and run Behat tests for a custom plugin under a custom theme:

php admin/tool/behat/cli/init.php --parallel=3 --add-core-features-to-theme="mytheme"
php admin/tool/behat/cli/run.php --tags="@tool_myplugin" --suite="mytheme"

=== Common options for running tests ===
==== Tests filters ====
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_file_upload''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_alert''': All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.
* '''@_switch_window''': All the tests that are using the '''I switch to "NAME" window''' step should be tagged as not all browsers manage them properly.
* '''@_switch_iframe''': All the tests that are using the '''I switch to "NAME" iframe''' steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

==== Output formats ====
Since Moodle 3.1 option for output is:
<code>
--format=pretty --out=/path/to/pretty.txt --format=moodle_progress --out=std
</code>
Before Moodle 3.1 option for output was:
<code>
--format='moodle_progress,pretty' --out=',/path/to/pretty.txt'
</code>
Following output formats are supported:
# '''progress''': Prints one character per step.
# '''pretty''': Prints the feature as is.
# '''junit''': Outputs the failures in JUnit compatible files.
# '''moodle_progress''': Prints Moodle branch information and dots for each step.
# '''moodle_list''': List all scenarios.
# '''moodle_stepcount''': List all features with total steps in each feature file. Used for parallel run.
# '''moodle_screenshot''': (since Moodle 3.1) Take screenshot and core dump of each step. With following options you can dump either or both.
## --format-settings '{"formats": "image"}'**: will dump image only
## --format-settings '{"formats": "html"}'**: will dump html only.
## --format-settings '{"formats": "html,image"}'**: will dump both.
## --format-settings '{"formats": "html", "dir_permissions": "0777"}'**
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format 'pretty' ('''-f pretty''') is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.

== Advance usage ==
=== Rerun failed scenarios ===
With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option
# '''Single run:''' --run="absolute_path_to_empty_file" (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)
# '''Parallel run:''' --rerun="absolute_path_to_empty_file_{runprocess}.txt --replace="{runprocess}" ({runprocess} will be replaced with the process number for recording fails in the specific run process).
'''Since Moodle 3.1 --rerun option don't accept any value, as it is handled internally by behat'''

=== Running behat with specified theme (Since Moodle 3.2) ===
You can run behat with any theme installed. To execute behat with specified theme use '''--suite={THEME_NAME}''' option, while running behat. By default the features in theme behat folder will be executed for the suite. But if you want to run all core features with the specific theme then initialise acceptance test with --add-core-features-to-theme={THEME_NAME}, e.g.

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
vendor/bin/behat --suite=clean --tags="@enrol_foobar"

</code>

That is a core theme but it will work with custom theme. No = or quotes needed around the theme name.

Make sure that <tt>$CFG->theme</tt> is '''not set''' in your config.php.

==== Override behat core context for theme suite ====
To override behat step definitions so as to run behat with specified theme, you should create a contexts within '''/theme/{MYTHEME}/tests/behat/''' with prefix behat_theme_{MYTHEME}_ and suffixed with the context being overridden. For example, if you want to override behat_mod_forum context, then you should create a class /theme/{MYTHEME}/tests/behat/mod_forum/behat_theme_{MYTHEME}_behat_mod_forum.php

==== Blacklist behat context or features to run in theme suite ====
To blacklist contexts/ features to be executed by theme suite you should create a /theme/{MYTHEME}/tests/behat/blacklist.json file with following format. Following will not use step_definitions from behat_grade and behat_navigation while running theme suite. Also, scenarios in auth/tests/behat/login.feature and grade/tests/behat/grade_hidden_items.feature won't be executed with theme suite.
<code>
{
"contexts": [
"behat_grade",
"behat_navigation",
],
"features": [
"auth/tests/behat/login.feature",
"grade/tests/behat/grade_hidden_items.feature",
]
}
</code>
==== Override core behat selectors ====
To override behat selectors in specific theme, you should create a class behat_theme_{MYTHEME}_behat_selectors in /theme/{MYTHEME}/tests/behat/behat_theme_{MYTHEME}_behat_selectors.php extending behat_selectors.

=== Use php built in web server ===
You can use php built-in-web server for executing behat runs. To do so:
# Open a command line interface and '''cd /to/your/moodle/dirroot'''
# '''php -S localhost:8000''' (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)
# Update $CFG->behat_wwwroot = localhost:8000; in config.php

=== Define custom options for parallel runs ===
You can set following custom config options for parallel runs via $CFG->behat_parallel_run. It's an array of options where 1st array is for 1st run and so on.
<code>
array (
'dbtype' => 'mysqli',
'dblibrary' => 'native',
'dbhost' => 'localhost',
'dbname' => 'moodletest',
'dbuser' => 'moodle',
'dbpass' => 'moodle',
'behat_prefix' => 'mdl_',
'wd_host' => 'http://127.0.0.1:4444/wd/hub',
'behat_wwwroot' => 'http://127.0.0.1/moodle',
'behat_dataroot' => '/home/example/bht_moodledata'
)
</code>

To set different selenium servers for parallel runs, you can use following. NOTE: Running parallel (headless) runs on different selenium servers avoid random focus failures.
<code>
$CFG->behat_parallel_run = array (
array ('wd_host' => 'http://127.0.0.1:4444/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4445/wd/hub'),
array ('wd_host' => 'http://127.0.0.1:4446/wd/hub'),
);
</code>

=== Write new tests and behat methods ===

If you want to write tests for your own integration, you can do so by creating new tests with format .feature. Follow instructions in [[Writing_acceptance_tests|this page]] to write new tests.

It is also possible to add new steps the moodle behat integration. In order to do so, you will have to create a new .php class with the prefix '''behat_'''. Copy the format from '''lib\behat\behat_base.php''', but set your class to extend the behat_base class instead of the MinkExtension. You can define new behat steps by declaring functions with the appropriate heading.

You will not be able to use these steps and features right away. Check [[Running_acceptance_test#New_step_definitions_or_features_are_not_executed|this section]] for instructions on how to update the behat integration.

For further information on how to create new steps definitions, check [[Acceptance testing/Custom acceptance steps]].

=== Running acceptance tests with different browser ===
By default behat will run with Firefox browser through Selenium. By adding the following code to your config.php you can change the selected browser that is run when behat is invoked. You will need to run php admin/tool/behat/cli/init.php for changes to take effect. Then use --profile='chrome'.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>
[[Acceptance_testing/Browsers|More info about alternative browsers]]

=== Start multiple selenium servers ===
From command line Start selenium servers at different ports (say 4444, 4445, 4446 for 3 parallel runs)
<code>
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4444 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4445 &
java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port 4446
</code>

Alternative way of running three Selenium servers in parallel:

$ printf %d\\n {4444..4446} | xargs -n 1 -P 3 java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar -port

=== Using Docker to start selenium server ===
==== What is Docker ====
Docker is a app container, it's a kind of virtual machine, but only for one app, service, so you can download
a docker image and run a selenium server without worry in how to configure selenium in your machine, one for chrome, others for firefox, you either don't need to install the browsers in your machine
To install docker follow this link; https://docs.docker.com/engine/installation/

==== Selenium docker images ====
There is many docker images available, for many browser, the complete list is in https://hub.docker.com/u/selenium/
for moodle you can use standalone version.
You can download specific selenium version too, for example, for firefox, moodle recommend selenium 2.53.1, see: [https://docs.moodle.org/dev/Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium What version do I need?]

so the command will be:
<code>
docker run -d -p4444:4444 selenium/standalone-firefox:2.53.1-beryllium
</code>
to see all available version click in tags. For firefox you can find at: https://hub.docker.com/r/selenium/standalone-firefox/tags/

==== Change config.php file ====
In config.php file you must change the $CFG->behat_wwwroot= to your network card (NIC) ip address, you can't use
localhost , 127.0.0.1, ... or selenium docker server will fail

=== Increasing timeouts ===

You may see errors such as:

<code>
Javascript code and/or AJAX requests are not ready after 10 seconds.
There is a Javascript error or the code is extremely slow.
</code>

Sometimes this indicates a genuine problem with the code, but if you are using a slow computer, it could just mean that the browser was not yet ready. You may find that the test works if you run it again. If you get this error frequently, it might be useful to increase the timeout.

It is possible to increase this timeout by adding a line in your config.php. (Requires Moodle versions 3.5 (from 3.5.6), 3.6 (from 3.6.4), or 3.7+.)

<code>
$CFG->behat_increasetimeout = 2;
</code>

This will increase all the timeouts by a factor of 2; if that isn't sufficient, you could use 3.

Increasing timeouts will make tests run a bit slower (because there are points where Behat waits up to a timeout to make sure something doesn't happen) so don't do this unless you need to.

== NOTE ==
# Start the Selenium server (in case you want to run tests that involves Javascript)
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running 'headless' Firefox and xvfm in a server environment)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''

=== Disable acceptance test environment ===
if you want to prevent access to test environment
<code>
php admin/tool/behat/cli/util.php --disable
</code>
'''Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.'''

== Trouble shooting ==

=== New step definitions or features are not executed ===
If you are adding new tests or steps definitions update the tests list
<code>
php admin/tool/behat/cli/util.php --enable
</code>
''' For parallel runs, all options for initialising parallel runs are valid '''

=== Tests are failing ===
If you followed all the steps and you receive an unknown weird error probably your system's Firefox version is not compatible with the Selenium version you are running. Please refer Working combinations to ensure you have correct [[Acceptance_testing/Browsers#Working_combinations_of_OS.2BBrowser.2Bselenium]] of them to run acceptance test.

=== Errors during setup (before test are launched) ===
Typical errors are:
* Behat requirement not satisfied: http://127.0.0.1/m/stable_master is not available, ensure you specified correct url and that the server is set up and started.
* Behat is configured but not enabled on this test site.

In order to fix those errors please check that: the behat_dataroot has correct write permissions and that the $CFG->behat* variables are placed before the lib/setup.php include:
require_once(__DIR__ . '/lib/setup.php');

=== Selenium server is not running ===
==== Chrome specific ====

If you are using chrome, you need to ensure that the driver matches the version of the installed chrome browser – which may change on OS updates/upgrades. Moodle or Selenium will not give the appropriate message – see [https://tracker.moodle.org/browse/MDL-67659/ MDL-67659]. One solution is the one suggested in the issue and use Andrew Nicols’ [https://github.com/andrewnicols/chromedriver-wrapper/ Chromedriver Wrapper] which will ensure you have the appropriate driver before running the tests.

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat
* Docker containers for Moodle Developers and Behat: https://github.com/moodlehq/moodle-docker
* Docker environment with Behat preconfigured : https://github.com/tobiga/docker_moodle_environment

== See also ==
* [[Acceptance testing for the mobile app]]

[[Category:Quality Assurance]][[Category:Behat]]

Coding

2020-04-06T11:10:49Z

Tim Hunt: /* Events */

This page is the top-level page describing Moodle's coding guidelines. It's the place to start if you want to know how to write code for Moodle.

==Moodle architecture==

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see [[Moodle architecture]].

==Plugins==

Moodle has a general philosophy of modularity. There are nearly 30 different standard types of plugins and even more sub-plugin types, however all of these plugin types work the same way. Blocks and activities are the only small exceptions.

See [[Plugins|Moodle plugins]] and [[Subplugins|Moodle sub-plugins]] for more information.

==Coding style==

Consistent [[Coding style|coding style]] is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our [[Coding_style|Moodle coding style]] document explains this standard.

==Security==

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Security|Moodle security guidelines]].

==XHTML and CSS==

It's important that Moodle produces strict, well-formed [http://en.wikipedia.org/wiki/HTML5 HTML 5] code (preferably backwards compatible with [[XHTML|XHTML 1.1]] if possible), compliant with all common accessibility guidelines (such as [http://www.w3.org/TR/WCAG20/ W3C WAG 2.0], [http://www.w3.org/TR/wai-aria-practices/ ARIA]).

CSS should be used for layout. Moodle comes with several themes installed. Beginning with version 2.7, only the 'Clean' theme comes in the base Moodle code. The 'standard' theme, which should be a plain theme suitable to act as a building block for other themes. That should contain the minimal styling to make Moodle look OK and be functional. Then Moodle comes with several other default themes that look good and demonstrate various techniques for building themes.

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

==JavaScript==

In general, everything in Moodle should work with JavaScript turned off in your browser. This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.

Features that are not available without JavaScript must be compliant with all accessibility standards.

See the [[JavaScript guidelines|Moodle JavaScript guidelines]] for more information.

==Internationalisation==

Moodle works in over 84 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code, comments and documentation, however, is English (AU).

Full details: [[String API]]

==Accessibility==

Moodle should work well for the widest possible range of people.

See [[Accessibility|Moodle Accessibility]] for more information.

==Usability==

See [[Interface_guidelines| Interface Guidelines]] (under construction)

==Performance==

The load any Moodle site can cope with will, of course, depend on the server and network hardware that it is running on. However there are some features (intended especially for developers) that are discouraged on production sites for performance reasons.

The most important property is scalability, so a small increase in the number of users, courses, activities in a course, and so on, only causes a correspondingly small increase in server load.

For more information and advice, see [[Performance and scalability|Performance and scalability]].

==Database==

Moodle has a powerful database abstraction layer that we wrote ourselves, called [[XMLDB_Documentation|XMLDB]]. This lets the same Moodle code work on MySQL/MariaDB, PostgreSQL, MS SQL Server and Oracle. There are know issues when using Oracle, it is not fully supported and is not recommended for production sites.

We have tools and API for [[DDL functions|defining and modifying tables]] as well as [[Data manipulation API|methods for getting data in and out]] of the database.

Overview: [[Database|Moodle Database]] guidelines

==Events==

Moodle allows inter-module communication via '''events'''. Modules can '''trigger''' specific events and other modules can choose to '''handle/observe''' those events.

See:
* [[Events API]] - Since Moodle 2.6 - in particular, note the [[Events_API#Events_naming_convention|Events naming convention]].

==Web services==

Should be implemented according to [[Web service API functions]] and [[How to contribute a web service function to core]], including the [[Web_service_API_functions#Naming_convention|Naming convention]].

==Manual testing==

All issues integrated into the core codebase are tested both during Integration, and subsequently by our testing team. While much of this testing is automated, there are many parts which cannot be automated, and manual testing is required.

Moodle has guidelines on [[Testing_instructions_guide|how to write clear testing instructions]] which we recommend you read and follow.

==Unit testing==

[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a framework called [https://github.com/sebastianbergmann/phpunit/ PHPUnit] that makes writing unit tests fairly simple.

See [[PHPUnit]] for more information.

==Acceptance testing==

PHPUnit covers mostly the internal implementation of functions and classes, the user interaction testing can be automated using the [http://behat.org Behat framework].

See [[Acceptance testing]] for more information.

==Third Party Libraries==
Moodle has a standard way to include third party libraries in your code. See https://docs.moodle.org/dev/Third_Party_Libraries

== Other standards ==

Please note that Moodle coding style and design is pretty unique, it is not compatible with [http://pear.php.net/manual/en/standards.php PEAR coding standards] or any other common PHP standards.

Events API

2020-04-06T10:56:17Z

Tim Hunt: /* Events naming convention */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objectid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters - indicating 'c'reate, 'r'ead, 'u'pdate or 'd'elete operation. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc. (event->contextinstanceid)
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode(). Floating point numbers cannot be used (see MDL-46701).
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. In a few cases, the educational level of an event depends on the context (site, course...) and/or the role (admin, teacher...) in these cases the selected educational level should be the most usual use case of that event. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_data()
| Returns standardised event data as an array (a good starting point for the information you need to handle an event!)
|-
| get_context()
| Returns event context
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the logging subsystem, and cannot be used later when logged event is displayed.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Backup/restore ==

When we perform a restore of an event we may need to map the 'objectid' and 'other' information in order to restore the event accurately. For example - take the event mod_assign\event\feedback_viewed which sets the 'objectid' to the value in the 'assign_grades' table and also stores the 'assignid' in 'other' which represents the id in the 'assign' table. When restoring this we need to map the data to the newly created 'assign_grades' and 'assign' entries as the event will be related to a new assignment, like when restoring to a new course. In order for the mapping to work it is necessary for the event to specify the relationship between these values by defining the static functions get_objectid_mapping() and get_other_mapping(). See the code example below -

<code php>
public static function get_objectid_mapping() {
return array('db' => 'assign_grades', 'restore' => 'grade');
}

public static function get_other_mapping() {
$othermapped = array();
$othermapped['assignid'] = array('db' => 'assign', 'restore' => 'assign');

return $othermapped;
}
</code>

The 'db' value is the name of the database table the id is linked to, and the 'restore' value is what the item is named during restore. The mapping can be found in the restore code. In this case it is located in mod/assign/backup/moodle2/restore_assign_stepslib.php where we can see the grades are mapped by the following in the function process_assign_grade() -

<code php>
$this->set_mapping('grade', $oldid, $newitemid, false, null, $this->task->get_old_contextid());
</code>

The $othermapped variable is an array of all the values in 'other' that require mapping. It is not necessary to list every single value in this array as they may not be related to a database table - only the ones that require mapping are needed.

If your event does not specify an 'objectid', then the get_objectid_mapping() is not necessary to declare. The same applies if there is no 'other' value. It is also common for 'other' to store data that doesn't need mapping at all, in this case simply declare the function but return false. For example, in mod_assign\event\submission_status_updated it is -

<code php>
public static function get_other_mapping() {
// Nothing to map.
return false;
}
</code>

There are some events such as assignsubmission_onlinetext\event\submission_created where mapping is not possible. In this case we assign the value to \core\event\base::NOT_MAPPED.

<code php>
public static function get_objectid_mapping() {
// No mapping available for 'assignsubmission_onlinetext'.
return array('db' => 'assignsubmission_onlinetext', 'restore' => \core\event\base::NOT_MAPPED);
}
</code>

This way we can distinguish in the logs which values were not mapped.

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

Technically, the verb should be in past participle form (e.g. creat'''ed''').

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_password_updated.php'''
| user_password_updated
| core
| user
| updated
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|replaced
|Similar to "Updated". But when the change does not apply to a clear identifiable identity and somehow is global, broader.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

It is important to trigger individual events for each and every action, bulk events are very strongly discouraged because existing observers would not receive important information. Changes from one to many would break backwards compatibility with observers and reporting.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]