Database Schema

2022-10-06T12:05:13Z

Marcusgreen:

The files available here are in [http://fabforce.net/dbdesigner4/ DBDesigner4] format. DBDesigner4 is a schema drawing program released under GPL.

The database schemas have been put together by [http://moodle.org/user/view.php?id=11101&course=11 Alberto Giampani], [http://moodle.org/user/view.php?id=192442&course=11 Dario Toledo] and [http://moodle.org/user/view.php?id=305352&course=5 Isaac Cueto]. We are also discussing a means of creating them automatically from the new XMLDB definitions with an XML transform.

Discussion of the database schemas happens either in the forum of the relevant module, or in the [https://moodle.org/mod/forum/view.php?id=55 General developer forum].

=Moodle 4.0 =

[http://www.examulator.com/er/4.0 Web view of the Moodle 4.00 schema] which is also grouped into common used components.

=Moodle 3.11=

[http://www.examulator.com/er/3.11 Web view of the Moodle 3.11 schema] which is also grouped into common used components.

=Moodle 3.10=

[http://www.examulator.com/er/3.10 Web view of the Moodle 3.10 schema] which is also grouped into common used components.

=Moodle 3.9=

[http://www.examulator.com/er/3.9 Web view of the Moodle 3.9 schema] which is also grouped into common used components.

=Moodle 3.7=

[https://www.examulator.com/er/3.7/index.html Web view of the Moodle 3.7 schema] which is also grouped into common used components.

=Moodle 3.6=

[https://www.examulator.com/er/3.6/index.html Web view of the Moodle 3.6 schema] which is also grouped into common used components.

=Moodle 3.5=

[https://www.examulator.com/er/3.5/index.html Web view of the Moodle 3.5 schema] which is also grouped into common used components. .

=Moodle 3.4=

[https://www.examulator.com/er/3.4/index.html Web view of the Moodle 3.4 schema] which is also grouped into common used components.

=Moodle 3.3=

[http://www.examulator.com/er/3.3/index.html Web view of the Moodle 3.3 schema] which is also grouped into common used components.

=Moodle 3.2=

[http://www.examulator.com/er/3.2/index.html Web view of the Moodle 3.2 schema] and a downloadable [http://www.examulator.com/er/moodle_32_erd.mwb Moodle 3.2 schema] by [http://www.moodleworld.com/moodle-entity-relationship-diagram-moodle-3-2-available-moodle3-2/ Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 3.1=

[http://www.examulator.com/er/3.1/index.html Web view of the Moodle 3.1 schema] and a downloadable [http://examulator.com/er/3.1/moodle_31_erd.mwb Moodle 3.1 schema] by [https://moodle.org/mod/forum/discuss.php?d=278052 Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 3.0=

[http://www.examulator.com/er/3.0/index.html Web view of the Moodle 3.0 schema] and a downloadable [http://www.examulator.com/er/moodle30_erd.mwb Moodle 3.0 schema] by [https://moodle.org/mod/forum/discuss.php?d=278052 Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 2.9=

[http://www.examulator.com/er/2.9/index.html Web view of the Moodle 2.9 schema] and a downloadable [http://www.examulator.com/er/moodle29_erd.mwb Moodle 2.9 schema] by [https://moodle.org/mod/forum/discuss.php?d=278052 Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 2.8=

[http://www.examulator.com/er/2.8/index.html Web view of the Moodle 2.8 schema] and a downloadable [http://www.examulator.com/er/moodle28_erd.mwb Moodle 2.8 schema] by [https://moodle.org/mod/forum/discuss.php?d=278052 Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 2.7=

[http://www.examulator.com/er/2.7/index.html Web view of the Moodle 2.7 schema] and a downloadable [http://www.examulator.com/er/moodle27_erd.mwb Moodle 2.7 schema] by [https://moodle.org/mod/forum/discuss.php?d=278052 Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 2.2=

[http://www.examulator.com/er/2.2/index.html Web view of the Moodle 2.2 schema] and a downloadable [http://www.examulator.com/er/moodle22_erd.mwb Moodle 2.2 schema] by [https://moodle.org/mod/forum/discuss.php?d=278052 Marcus green] can be opened by [http://www.mysql.com/products/workbench MYSQL Workbench] tool.

=Moodle 1.8=

http://moodle.org/file.php/5/moddata/forum/28/376698/moodle_1.8_data_structure.rar

=Moodle 1.7=

http://moodle.org/file.php/11/moddata/forum/110/268325/db-edudist-Moodle-1.7_.rar

=Moodle 1.5.3=

http://moodle.org/file.php/11/moddata/forum/110/267644/Db-Edudist-Moodle1.5.3-xml.rar

[[Category:XMLDB]]
[[Category:DB]]
[[Category:Interfaces]]

Setting up VSCode

2022-09-29T15:48:04Z

Marcusgreen: /* PHP Code Sniffer*/

Setting up VSCode

2022-07-14T10:00:56Z

Marcusgreen: tweak to xdebug commentary

Setting up VSCode

2022-07-14T09:35:45Z

Marcusgreen: Set location of code for xdebug

Writing acceptance tests

2022-01-31T19:32:57Z

Marcusgreen: /* When you define more steps in your plugin, make it clear they come from your plugin */

== 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 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 assignment 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:
<syntaxhighlight lang="gherkin">
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"
</syntaxhighlight>
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:
<syntaxhighlight lang="gherkin">
@mod @mod_yourplugin @javascript
Feature: Here comes a description of your user story.
</syntaxhighlight>
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:
<syntaxhighlight lang="gherkin">
@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
</syntaxhighlight>
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:
<syntaxhighlight lang="gherkin">
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 |
</syntaxhighlight>
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:
<syntaxhighlight lang="gherkin">
Then "STRING_IN_ROW" row "COLUMN_HEADER" column of "TABLE_ID" table should contain "VALUE_TO_CHECK"
</syntaxhighlight>
or
<syntaxhighlight lang="gherkin">
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 |
</syntaxhighlight>
====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
<syntaxhighlight lang="gherkin">
@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"
...
</syntaxhighlight>
======Field groups======
This section describes how you can use the step definitions
<syntaxhighlight lang="gherkin">
When I set the following fields to these values:
...
When I set the field "([^"]|\"*)" to "([^"]|\"*)"
</syntaxhighlight>
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
<syntaxhighlight lang="gherkin">
identifierOfYourField[keyOfTheSpecificInput]
</syntaxhighlight>
Examples would be:
<syntaxhighlight lang="gherkin">
When I set the following fields to these values:
| myDate[day] | 21 |
| myDate[month] | 12 |
| myDate[hour] | 14 |
| myDuration[number] | 10 |
| myDuration[unit] | days |
</syntaxhighlight>
======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:
*<nowiki>## yesterday ##</nowiki>
*<nowiki>## 2 days ago ##</nowiki>
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:
*<nowiki>## yesterday ## myformat ##</nowiki>
These formats can be used as outlined in http://php.net/manual/en/function.date.php.
This can be combined with the field groups:
<syntaxhighlight lang="gherkin">
When I set the following fields to these values:
| myDate[day] | ##yesterday##%d## |
| myDate[month] | ##yesterday##%B## |
| myDate[year] | ##yesterday##%Y## |
</syntaxhighlight>
====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
<syntaxhighlight lang="gherkin">
And I click on "Submit all and finish" "button" in the "Confirmation" "dialogue"
</syntaxhighlight>
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:
<syntaxhighlight lang="gherkin">
Given I am on the "Quiz 1" "mod_quiz > View" page logged in as "manager"
Given I am on the "C1" "Course" page
</syntaxhighlight>
To make this work, in your plugin's <tt>behat_plugintype_plugingname</tt> class, you need to implement the functions <tt>resolve_page_url</tt> and <tt>resolve_page_instance_url</tt> methods. Once again, the detailed instructions about how 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:
<syntaxhighlight lang="php">
class local_myplugin_generator extends component_generator_base {
public function create_thing($thing) {
global $DB;
$DB->insert_record('local_myplugin_things', $thing);
}
}
</syntaxhighlight>
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():
<syntaxhighlight lang="php">
class behat_local_myplugin_generator extends behat_generator_base {

protected function get_creatable_entities(): array {
return [
'things' => [
'datagenerator' => 'thing',
'required' => ['name']
],
];
}
}
</syntaxhighlight>
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".
<syntaxhighlight lang="gherkin">
Given the following "local_myplugin > things" exist:
| name |
| thing1 |
| thing2 |
</syntaxhighlight>
==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>.

===PHPDoc comments to map scenario steps===
PHPDoc style comments before functions can be used to map to your .scenario files. Read more about this here

https://behat.org/en/latest/user_guide/context/definitions.html

When you define more steps in your plugin, make it clear they come from your plugin
[[Category:Behat]]

Setting up VSCode

2021-11-15T23:07:00Z

Marcusgreen: /* Behat/Gherkin/Cucumber Formatting */

Talk:Main Page

2021-09-16T10:32:43Z

Marcusgreen:

'''Note: This is not the place to ask questions. If you have a development related question, ask it in the [https://moodle.org/mod/forum/view.php?id=55 General Developer forum].'''

== Broken link in accessibility section ==

Please note that on the following page: https://docs.moodle.org/dev/Accessibility the link to the British standard is broken: http://www.southampton.ac.uk/web4all/standards/BS_16steps/

===Previously broken link in accessibility section fixed===
Please note that the page at https://docs.moodle.org/dev/Accessibility now correctly links to https://www.access8878.co.uk/getting-started-with-bs-8878/16-steps.aspx [[User:German Valero|German Valero]] ([[User talk:German Valero|talk]])

===Missing (?) link to PHPStorm in "Developer Tools" category ===
I don't know what's the condition to appear on the main dev page, but as I'm using IntelliJ/PHPStorm I noticed it's article was missing there [[Setting_up_PhpStorm]]

And more importantly the link to VSCode is missing https://docs.moodle.org/dev/Setting_up_VSCode

Javascript Modules

2021-06-19T21:51:37Z

Marcusgreen:

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running [[Grunt]], even with the cachejs config setting set to false (i.e. "Development mode").

Note that, for Moodle 3.10 and up (see MDLSITE-6130), any new Javascript module '''must''' be written on ES6.

== Install NVM and Node ==

The recommended way of installing NodeJS is via the [https://github.com/nvm-sh/nvm Node Version Manager], or NVM. NVM allows you to have several different versions of NodeJS installed at and in-use at any once on your computer. Supported versions of Moodle all use version {{NodeJSExactVersion}} of NodeJS.

https://github.com/nvm-sh/nvm#installing-and-updating

Confirm it is working:

$ nvm --version
0.35.3

After you have installed '''nvm''', you should install the correct version of NodeJS by running the following commands from your Moodle directory:

nvm install
nvm use

If your primary use of NodeJS is for Moodle then we recommend that you set NodeJS version {{NodeJSExactVersion}} as your default version. You can do this by running:

nvm alias default {{NodeJSExactVersion}}

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

Once this is done, you can run the the following commands from your Moodle directory:

npm install

'''This may mention vulnerabilities, that's fine and doesn't apply.'''

npm install -g grunt-cli

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run [[Grunt]] in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Development mode (Moodle v3.10 and above) ==

All the above for Moodle 3.8 and up applies, plus (see MDLSITE-6130), any new Javascript module must be written on ES6.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

Note that, for Moodle 3.10 and up (see MDLSITE-6130), any new Javascript module must be written on ES6.

The call from a PHP file takes the same format
<code>
$PAGE->requires->js_call_amd('myplugin/myfile','init');
</code>

And a minimal ES6 file will work with
<code>
export const init = () => {
window.console.log('we have been started');
};
</code>

=== Export default ===
There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

=== Inline Javascript ===
Another important note is that ES6 support is only for stand alone Javascript files because it relies on the compilation from Babel and Grunt. That means any inline Javascript (either in PHP or in Mustache templates) won't support the ES6 features. Instead it would be best to keep the inline Javascript as minimal as possible and only use it to load a stand alone Javascript module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

export const init = () => {
document.addEventListener('change', e => {
const someNode = e.target.closest('.someclass');
if (someNode) {
alert('It changed!');
}
});
};
</code>

For older versions of Moodle prior to 3.8, you will need to use the legacy ES5 format instead:
<code javascript>
define([], function() {

return {
init: function() {
document.addEventListener('change', function(e) {
var someNode = e.target.closest('.someclass');
if (someNode) {
alert('It changed!');
}
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
import jQuery from 'jquery'; // We recommend that you strongly consider whether you really need jQuery. It is typically not needed in modern code.
import * as Str from 'core/str';
import Ajax from 'core/ajax';

export const init = config => {
};
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
export const init = (first, last) {
window.console.log(`The first name was '${first}' and the last name was '${last}'`);
};
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

import * as Str from 'core/str';

/**
* Reveal all of the hidden notes.
*/
const showAllNotes = () => {
document.querySelectorAll('.note.hidden').map(note => note.removeClass('hidden'));
};

/**
* Hide all of the notes.
*/
const hideAllNotes = () => document.querySelectorAll('.note').map(note => note.addClass('hidden'));

/**
* Return a personalised, formal, greeting.
*
* @param {String} name The name of the person to greet
* @returns {Promise}
*/
export const formal = name => Str.get_string('formallygreet', 'block_overview', name);

/**
* Return a personalised, informal, greeting.
*
* @param {String} name The name of the person to greet
* @returns {Promise}
*/
export const informal = name => {
return Str.get_string('informallygreet', 'block_overview', name);
};
</code>

It's important to note tha tonly functions which are exported will be callable from outside the module. These are part of the public API.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? In a limited number of situations you may not know the modules that you need until you call them. You can make use of dynamic imports to import them when you know what they are. Note: This is not the recommended approach in most cases.

<code javascript>
export const showTheThing = thingToShow => {
// Load the module for this thing.
import(`local_examples/local/types/type_${thingToShow.modname}`)
.then(thingModule => {
window.console.log(`The ${thingToShow.modname} is now available under thingModule within this scope`);

return thingModule;
});
};
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
// DO NOT DO THIS - IT DOES NOT WORK IN MOODLE
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'init', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
import Countdown from 'theme_mytheme/jquery.countdown');
import $ from 'jquery';

export const init = params => {
$('#clock').countdown(params.targetItem, event => {
$(event.target).html(event.strftime('%D days %H:%M:%S'));
});
};
</code>

2. Call your Javascript module from your template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="theme_mytheme-clock-{{uniqid}}"></span>
{{#js}}
require(['theme_mytheme/countdowntimer'], function(myModule) {
myModule.init({
targetItem: 'theme_mytheme-clock-{{uniqid}}'
});
});
{{/js}}
</code>

Note: If you feel that you need to work around MDL-62468, then you should probably be putting the data into the DOM in your template via data Attributes, or loading it via a Web Service.

Another example of adding a 3rd-party library to a Moodle plugin (by Ruslan Kabalin)

If you want use https://github.com/R-TEK/colr_pickr in your plugin but this module isn't RequireJS-compatible.

You need to configure requirejs in your plugin to use third-party library:

<code php>
$config = ['paths' => ['colorpicker' => 'CDN or local path...']];
$requirejs = 'require.config(' . json_encode($config) . ')';
$PAGE->requires->js_amd_inline($requirejs);
</code>
Then in your JS module in the plugin:
<code javascript>
define([colorpicker], function(ColorPicker) {
const button = document.getElementById('my_picker');
let picker = new ColorPicker(button, '#ff0000');
}
</code>

And another example of using https://github.com/itsjavi/bootstrap-colorpicker (that has a [[jQuery]] dependency) with native ES6 JS:

NOTE: It is advised to move away from [[jQuery]] related plugins, as Moodle core is moving away from jQuery.
<br>
<code javascript>
import ColourPicker from 'local_myplugin/bootstrap-colorpicker';

const myElement = document.querySelector('.myelement');
const picker = new ColourPicker(myElement);
</code>

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== Troubleshooting ==

=== npm-shrinkwrap.json sha1 / sha512 changes ===

If grunt changes all the hashes in npm-shrinkwrap.json then try this:

rm -rf node_modules && npm i

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.
*MDL-67327 JavaScript issues when not following the official documentation, since Moodle 3.8
*[https://moodle.org/mod/forum/discuss.php?d=405829 Error from grunt watch - Moodle 3.9] Forum Discussion

[[Category:AJAX]]
[[Category:Javascript]]

Setting up VSCode

2021-05-24T06:54:53Z

Marcusgreen: /* Auto trim trailing white space */

Running acceptance test

2021-01-28T14:52:43Z

Marcusgreen: /* Running behat with specified theme (Since Moodle 3.2) */

== 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=[classic | customtheme ]''' 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
</code>
The first time init runs can be time consuming as it creates a paralell set of tables to core, i.e. bh_user,bh_assign etc. After init the tests can be run with the alternative theme as follows.
<code>
vendor/bin/behat --suite=classic --tags="@enrol_foobar"
</code>

If there is no --suite= parameter it will fall back to the default boost 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]]

Running acceptance test

2021-01-28T14:48:38Z

Marcusgreen: /* Running behat with specified theme (Since Moodle 3.2) */

== 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=[classic | customtheme ]''' 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=classic --tags="@enrol_foobar"
</code>

If there is no --suite= parameter it will fall back to the default boost 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]]

Running acceptance test

2021-01-28T12:21:44Z

Marcusgreen: /* Running behat with specified theme (Since Moodle 3.2) */

== 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, (the clean theme has been replaced by classic in later versions of Moodle). 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]]

Callbacks

2021-01-19T21:03:28Z

Marcusgreen: /* List of one-to-many callbacks */

Moodle does not have well-defined Hooks API but still allows plugins to hook into different processes by '''implementing callbacks'''. See also [[Communication Between Components]].

Some old APIs that were created before object-oriented programming use only callbacks. One of them is [[Activity modules]].

==Types of callbacks in Moodle==

=== Callback functions one-to-many ===

Core has a "hook point" where it allows plugins to execute some code, modify variables or return a result. Sometimes (especially for old callbacks) only plugins of a specific plugin type are allowed, however this is not recommended for the new callbacks because the list of callbacks is now cached and performance is not a constraint any more. If plugins want to implement the function for this callback they normally must place it in '''lib.php''' with the name '''pluginfullname_callbackname()'''. Here pluginname should be a full plugin name with a prefix, however activity modules can often omit the "mod_" prefix for historical reasons. Implementing this type of callback is optional and the "hook point" does not care how many and which plugins implement callback. Also "hook point" does not check if the plugin is enabled on this site, inside the callback plugins must check it themselves if it is important. Methods '''get_plugin_list_with_function()''' and '''get_plugins_with_function()''' are normally used in the "hook points" to find all plugins implementing a callback.

This document aims to cover ALL callbacks of this type that are present in Moodle core APIs or in standard Moodle plugins.

=== Callback functions one-to-one ===

Core API (or plugins such as blocks or reports) looks for and executes a method from the plugin/component that "owns" some entity, usually for checking permissions, pre-processing or providing the human-readable representation of this entity. Similar to one-to-many callbacks, the component/plugin must define a function with the name '''pluginfullname_callbackname()''' in lib.php . In some cases the function ''must'' be present or otherwise an exception is thrown or debugging message is displayed. Methods '''component_callback()''' and '''component_callback_exists()''' are normally used to find an implementation of a callback. Unlike one-to-many callbacks the implementing functions can exist not only in plugins but also in core components.

The list of one-to-one callbacks may not be 100% complete in this document, the aim is to cover the "magic" functions that are actually used despite IDE hints.

=== Other ===

* '''Files in the specific location'''. Core APIs may look for plugins that have a file with a specific file name, for example '''version.php''', '''settings.php''', '''styles.css''', '''module.js''', files in '''db/''' folder, etc. See [[Plugin files]]
* '''Event observers'''. Each plugin can implement event observers that execute code when event is triggered. See [[Events API#Event_dispatching_and_observers|Events API]] about how to listen to events. Event observers can not always substitute callbacks because they do not return any value and can only happen in case of event. Many "hook points" are necessary before something has happened or when nothing is happening at all, for example a report/summary is gathered. However if it is possible to achieve the desired outcome with event observer, Moodle will not accept requests for adding a "hook point".
* Callbacks that are specified in the db/* file, for example in '''db/service.php''' developers must specify callback responsible for implementing web service, in '''db/tags.php''' developers specify callback for finding tagged items, etc. These types of callbacks are not covered on this page, information about them can be found in the respective APIs.

== Callbacks and external / webservices / consumers (mobile / apps) support ==

=== The problem ===

Our external functions are able to [[Web service API functions|perform a lot of actions]] against core. Those external functions use to implement their functionality reusing [[Core APIs]]. And, those APIs can contain hook points/callbacks to customize Moodle behavior.

Of course, ultimately, those external functions are used by the [[Web_services| web services layer]] providing all the functionality over REST/XMLRCP/SOAP "protocols". All those "clients" consuming Moodle Webservices (integrations in general, mobile & desktop apps...) should work ok, and we must guarantee that all the code executed in those underlying external functions (that may include hook points/callbacks) is supported by them.

In the other side, some of those callbacks may be focussed entirely in the web version of Moodle and have no application outside from there. Also, sometime, there are callbacks which goal is incompatible with uses from web service consumers, mainly because the consumers don't support this or that Moodle functionality used by the callback implementations.

Imagine a callback that provides to the consumer with something that it's not able to manage (say a mustache template, or a moodle form, or any other stuff in general that only core is able to provide). It's a pretty "possible" case a we need a way to handle it in an organised way.

=== The solution ===

To be able advance with those "problematic" hooks (not being supported by web-service consumers), it has been agreed to proceed with the following points in order to allow them to work via web, avoiding them to impact to consumers and registering the need of introducing (future) viable solutions to enable consumers to work with them.

All the following points must be considered as real requirements in order to allow a new callback (called from externals/web services) to land to core.

# '''Create a linked MOBILE issue''' requesting the callback to be supported in the app (for the record and future reference). Clearly explaining which are the externals / web services affected, what should be supported and, ideally, a way to provide that.
# '''Clearly indicate in the issue''' introducing the new callback if the hook is supported or not via WebServices. Callbacks documentation (below in this page) '''must include the comment''' ''"Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-xxxx and MOBILE-xxxx for more info."''" (where the MDL and MOBILE issues are the related ones).
# '''Add manual tests''' in the issue for checking that the related functionality in the mobile / desktop app is not broken and everything continues working ok.
# Check that the '''modified code or APIs do not impact on the external / WebServices''' API. You can just check if the modified function is used by the external API just adding a debug message and then running WebServices.
# If you need to add code in an API already used by the external API, you can always '''use the WS_SERVER constant''' to check if the current request comes from the WS layer to '''avoid its execution'''. With links to the corresponding MDL-xxxx and MOBILE-xxxx issues.
# In any case, '''it's the responsibility of every plugin implementing a not compatible callback to prevent any action''' that may affect / impact the WS layer. Core (hook points) will always perform the calls to the callbacks, unconditionally.

== List of Moodle callbacks ==

=== List of one-to-many callbacks ===

To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

{| class="nicetable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Navigation, see [[Navigation API]]'''
|-
| extend_navigation_course
| *
|
| before Moodle 3.0 was only supported by ''report'' and ''tool'' plugin types
|-
| extend_settings_navigation
| local, booktool
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation
| local
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation_user_settings
| *
| 3.0+
| before Moodle 3.0 was only supported by ''tool'' plugin types
|-
| extend_navigation_category_settings
| *
| 3.0+
|
|-
| extend_navigation_frontpage
| *
| 3.1+
|
|-
| extend_navigation_user
| *
| 3.1+
|
|-
| colspan=4 align=center | '''My profile, see [[My profile API]]'''
|-
| myprofile_navigation
| *
| 2.9+
|
|-
| colspan=4 align=center | '''Before-actions hooks'''
|-
| course_module_background_deletion_recommended
| *
| 3.2+
| see [https://github.com/moodle/moodle/blob/MOODLE_32_STABLE/lib/upgrade.txt#L142 upgrade.txt]
|-
| pre_block_delete
| *
| 3.1+
|
|-
| pre_course_category_delete
| *
| 3.1+
|
|-
| pre_course_delete
| *
| 3.1+
|
|-
| pre_course_module_delete
| *
| 3.1+
|
|-
| pre_user_delete
| *
| 3.1+
|
|-
| colspan=4 align=center | '''[[Login_callbacks]]'''
|-
| [[Login_callbacks#after_config | after_config]]
| *
| 3.8+
| Triggered as soon as practical on every moodle bootstrap after config has been loaded. The $USER object is available at this point too.
|-
| [[Login_callbacks#after_require_login | after_require_login]]
| *
| 3.7+
| eg Add permissions logic across a site or course
|-
| [[Login_callbacks#check_password_policy | check_password_policy]]
| *
| 3.6+
|
|-
| [[Login_callbacks#print_password_policy | print_password_policy]]
| *
| 3.8+ (WIP)
|
|-
| [[Login_callbacks#pre_signup_requests | pre_signup_requests]]
| *
| 3.5
| eg to do actions before sign up such as acceptance of policies, validations, etc
|-
| [[Login_callbacks#extend_change_password_form | extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_set_password_form | extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_forgot_password_form | extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_signup_form | extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_change_password_form | validate_extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_set_password_form | validate_extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_forgot_password_form | validate_extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_signup_form | validate_extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#post_change_password_requests | post_change_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user changes password.
|-
| [[Login_callbacks#post_set_password_requests | post_set_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user resets password.
|-
| [[Login_callbacks#post_forgot_password_requests | post_forgot_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user submits a password reset request.
|-
| [[Login_callbacks#post_signup_requests | post_signup_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user creates an account.
|-
| colspan=4 align=center | '''Page rendering, see [[Output_callbacks]]'''
|-
| [[Output_callbacks#add_htmlattributes | add_htmlattributes]]
| *
| 3.3+
| eg Add open graph xml namespace attributes
|-
| [[Output_callbacks#before_footer | before_footer]]
| *
| 3.3+
| eg injecting JS across the site, like analytics
|-
| [[Output_callbacks#before_http_headers | before_http_headers]]
| *
| 3.3+
| Setting http headers across the site like CSP
|-
| [[Output_callbacks#before_standard_html_head | before_standard_html_head]]

| *
| 3.3+
| A better API alternative to appending to $CFG->additionalhtmlhead
|-
| [[Output_callbacks#before_standard_top_of_body_html | before_standard_top_of_body_html]]
| *
| 3.3+
|
|-
| [[Output_callbacks#render_navbar_output | render_navbar_output]]
| *
| 3.2+
|
|-
| colspan=4 align=center | '''Course module edit form'''
|-
| coursemodule_edit_post_actions
| *
| 3.1+
|
|-
| coursemodule_standard_elements
| *
| 3.1+
| Takes parameters $formwrapper and $mform, allows manipulation of editing form, e.g. additional fields. See https://github.com/marcusgreen/moodle-local_callbacks
|-
| coursemodule_validation
| *
| 3.1+
|
|-
| colspan=4 align=center | '''Modules'''
|-
| check_updates_since
| mod
| 3.2+
| See [[NEWMODULE_Documentation]]
|-
| dndupload_register
| mod
|
|
|-
| colspan=4 align=center | '''Admin'''
|-
| bulk_user_actions
| *
| 3.9+
| Any plugin typically an admin tool can add new bulk user actions
|-
| colspan=4 align=center | '''Other'''
|-
| get_fontawesome_icon_map
| *
| 3.3+
| https://docs.moodle.org/dev/Moodle_icons#Font_awesome_icons
|-
| get_question_bank_search_conditions
| local
|
|
|-
| oauth2_system_scopes
| *
| 3.3+
|
|-
| rss_get_feed
| *
|
|
|-
| supports_logstore
| report
|
|
|-
| get_shortcuts
| ltisource
| 3.1+
|
|-
| before_launch
| ltisource
| 2.8+
|
|-
| [[Miscellaneous_callbacks#control_view_profile | control_view_profile]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#store_profiling_data | store_profiling_data ]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#override_webservice_execution | override_webservice_execution]]
| *
| 3.6+
|
|-
| colspan=4 align=center | '''Deprecated'''
|-
| cron
| *
|
| See [[Task API]]
|-
| delete_course
| mod,report,coursereport,format
|
| Replace with observer to course_contents_deleted event
|-
| print_overview
| mod
| up to 3.2
| New dashboard uses [[Calendar API]] to populate events on the timeline
|-
| report_extend_navigation
| coursereport
|
| Plugin type ''coursereport'' is deprecated, plugin type ''report'' should be used instead
|}

'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions

=== List of one-to-one callbacks ===

To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

{| class="nicetable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Comments support''', see [[Comment API]]
|-
| comment_add
| *
|
|
|-
| comment_display
| *
|
|
|-
| comment_permissions
| *
|
|
|-
| comment_template
| *
|
|
|-
| comment_url
| *
|
|
|-
| comment_validate
| *
|
|
|-
| colspan=4 align=center | '''Gradebook'''
|-
| export_%_settings_definition
| gradeexport
|
| % is a plugin name ''without'' prefix
|-
| import_%_settings_definition
| gradeimport
|
| % is a plugin name ''without'' prefix
|-
| report_%_profilereport
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| report_%_settings_definition
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| colspan=4 align=center | '''Groups support''', see [[Groups API]]
|-
| allow_group_member_remove
| *
|
|
|-
| restore_group_member
| *
|
| For plugins that create their own groups
|-
| colspan=4 align=center | '''Installation and upgrade'''
|-
| xmldb_%_install
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_install_recovery
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_uninstall
| *
|
| Located in db/uninstall.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_upgrade
| *
|
| Located in db/upgrade.php , % refer to the full plugin name, in case of modules without prefix
|-
| colspan=4 align=center | '''LTI source'''
|-
| add_instance_hook
| ltisource
|
|
|-
| ''messagetype''
| ltisource
|
| Callback name is the type of the message
|-
| colspan=4 align=center | '''Question bank support''', see [[Question API]]
|-
| question_pluginfile
| *
|
|
|-
| question_preview_pluginfile
| *
|
|
|-
| questions_in_use
| *
| since 3.7.5, 3.8.2 (previously only "mod")
|
|-
| colspan=4 align=center | '''Ratings support''', see [[Rating API]]
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_get_item_fields
| *
|
|
|-
| rating_permissions
| *
|
|
|-
| rating_validate
| *
|
|
|-
| colspan=4 align=center | '''Themes'''
|-
| $THEME->csspostprocess
| theme
|
|
|-
| $THEME->extralesscallback
| theme
|
|
|-
| $THEME->lessvariablescallback
| theme
|
|
|-
| page_init
| theme
|
|
|-
| colspan=4 align=center | '''Modules: Calendar and dashboard'''
|-
| core_calendar_event_action_shows_item_count
| mod
| 3.3+
|
|-
| core_calendar_is_event_visible
| mod
| 3.3+
|
|-
| core_calendar_provide_event_action
| mod
| 3.3+
|
|-
| colspan=4 align=center | '''Modules: Course cache'''
|-
| cm_info_dynamic
| mod
|
|
|-
| cm_info_view
| mod
|
|
|-
| get_coursemodule_info
| mod
|
|
|-
| colspan=4 align=center | '''Modules: Course reset'''
|-
| reset_course_form_defaults
| mod
|
|
|-
| reset_course_form_definition
| mod
|
|
|-
| reset_userdata
| mod
|
|
|-
| colspan=4 align=center | '''Modules'''
|-
| delete_instance
| mod
|
|
|-
| dndupload_handle
| mod
|
|
|-
| export_contents
| mod
|
| Used in WS get_course_contents
|-
| extend_settings_navigation
| mod,booktool
|
|
|-
| extends_navigation
| mod
|
|
|-
| get_completion_active_rule_descriptions
| mod
| 3.3+
| Must be present for modules implementing custom completion rules
|-
| get_completion_state
| mod
|
|
|-
| get_extra_capabilities
| mod
|
|
|-
| get_file_areas
| mod
|
|
|-
| get_recent_mod_activity
| mod
|
|
|-
| get_shortcuts
| mod
| 3.1+
|
|-
| grade_item_update
| mod
|
|
|-
| grading_areas_list
| mod
|
|
|-
| print_recent_activity
| mod
|
|
|-
| print_recent_mod_activity
| mod
|
|
|-
| refresh_events
| mod
|
|
|-
| rescale_activity_grades
| mod
| 3.1+
|
|-
| scale_used_anywhere
| mod
|
|
|-
| update_grades
| mod
|
|
|-
| user_complete
| mod
|
|
|-
| user_outline
| mod
|
|
|-
| colspan=4 align=center | '''Glossary formats'''
|-
| glossary_print_entry_%
| for glossary formats
|
| Glossary formats is not a plugin type yet, however the list of formats is not hardcoded in the mod_glossary, instead the methods similar to callbacks are used for each subfolder in mod/glossar/format. % refer to the subfolder name, the functions are expected in lib.php
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| colspan=4 align=center | '''Other'''
|-
| global_db_replace
| block
|
|
|-
| inplace_editable
| *
|
| See [[Inplace editable]]
|-
| output_fragment_*
| *
| 3.1+
| see [[Fragment]]
|-
| page_type_list
| *
|
| Used when displaying page types in block configuration
|-
| params_for_js
| atto
|
|
|-
| pluginfile
| *
|
| Callback checking permissions and preparing the file for serving plugin files, see [[File API]]. Note, in case of ''block'' plugins the list of arguments is slightly different
|-
| restore_role_assignment
| *
|
| For plugins that create their own role assignments
|-
| strings_for_js
| atto
|
|
|-
| supports
| *
|
| Required for activity modules
|-
| colspan=4 align=center | '''Deprecated'''
|-
| ajax_section_move
| format
| up to 2.3
| See [[Course formats]]
|-
| ajax_support
| format
| up to 2.3
| See [[Course formats]]
|-
| delete_course
| mod
| up to 3.1
| use event observer
|-
| display_content
| format
| up to 2.3
| See [[Course formats]]
|-
| get_post_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| get_section_name
| format
| up to 2.3
| See [[Course formats]]
|-
| get_section_url
| format
| up to 2.3
| See [[Course formats]]
|-
| get_types
| mod,ltisource
| up to 3.0
| Replaced with ''get_shortcuts'' in 3.1
|-
| get_view_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| load_content
| format
| up to 2.3
| See [[Course formats]]
|-
| scale_used
| mod
| up to 3.0
|
|-
| uses_sections
| format
| up to 2.3
| See [[Course formats]]
|-
| question_list_instances
| mod
| up to 3.8
| Use "questions_in_use" instead
|}

'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions

== Adding new callbacks to core ==

If you are preparing a patch for core which adds a new callback here are some things which should be considered.

TBA see https://tracker.moodle.org/browse/MDL-60510

Setting up VSCode

2020-11-14T15:43:38Z

Marcusgreen: /* Code Formatting */

Setting up VSCode

2020-11-07T22:20:31Z

Marcusgreen: /* Debugging */

2020-10-23T09:56:04Z

Marcusgreen:

Javascript Modules

2020-10-12T08:47:47Z

Marcusgreen: /* ES6 Modules (Moodle v3.8 and above) */

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running [[Grunt]], even with the cachejs config setting set to false (i.e. "Development mode").

Note that, for Moodle 3.10 and up (see MDLSITE-6130), any new Javascript module '''must''' be written on ES6.

== Install NVM and Node ==

The recommended way of installing NodeJS is via the [https://github.com/nvm-sh/nvm Node Version Manager], or NVM. NVM allows you to have several different versions of NodeJS installed at and in-use at any once on your computer. Supported versions of Moodle all use version {{NodeJSExactVersion}} of NodeJS.

https://github.com/nvm-sh/nvm#installing-and-updating

Confirm it is working:

$ nvm --version
0.35.3

After you have installed '''nvm''', you should install the correct version of NodeJS by running the following commands from your Moodle directory:

nvm install
nvm use

If your primary use of NodeJS is for Moodle then we recommend that you set NodeJS version {{NodeJSExactVersion}} as your default version. You can do this by running:

nvm alias default {{NodeJSExactVersion}}

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

Once this is done, you can run the the following commands from your Moodle directory:

npm install

'''This may mention vulnerabilities, that's fine and doesn't apply.'''

npm install -g grunt-cli

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run [[Grunt]] in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Development mode (Moodle v3.10 and above) ==

All the above for Moodle 3.8 and up applies, plus (see MDLSITE-6130), any new Javascript module must be written on ES6.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

Note that, for Moodle 3.10 and up (see MDLSITE-6130), any new Javascript module must be written on ES6.

The call from a PHP file takes the same format
<code>
$PAGE->requires->js_call_amd('myplugin/myfile','init');
</code>

And a minimal ES6 file will work with
<code>
export const init = () => {
window.console.log('we have been started');
};
</code>

=== Export default ===
There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

=== Inline Javascript ===
Another important note is that ES6 support is only for stand alone Javascript files because it relies on the compilation from Babel and Grunt. That means any inline Javascript (either in PHP or in Mustache templates) won't support the ES6 features. Instead it would be best to keep the inline Javascript as minimal as possible and only use it to load a stand alone Javascript module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== Troubleshooting ==

=== npm-shrinkwrap.json sha1 / sha512 changes ===

If grunt changes all the hashes in npm-shrinkwrap.json then try this:

rm -rf node_modules && npm i

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.
*MDL-67327 JavaScript issues when not following the official documentation, since Moodle 3.8

[[Category:AJAX]]
[[Category:Javascript]]

Javascript Modules

2020-10-12T08:47:18Z

Marcusgreen: /* ES6 Modules (Moodle v3.8 and above) */

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running [[Grunt]], even with the cachejs config setting set to false (i.e. "Development mode").

Note that, for Moodle 3.10 and up (see MDLSITE-6130), any new Javascript module '''must''' be written on ES6.

== Install NVM and Node ==

The recommended way of installing NodeJS is via the [https://github.com/nvm-sh/nvm Node Version Manager], or NVM. NVM allows you to have several different versions of NodeJS installed at and in-use at any once on your computer. Supported versions of Moodle all use version {{NodeJSExactVersion}} of NodeJS.

https://github.com/nvm-sh/nvm#installing-and-updating

Confirm it is working:

$ nvm --version
0.35.3

After you have installed '''nvm''', you should install the correct version of NodeJS by running the following commands from your Moodle directory:

nvm install
nvm use

If your primary use of NodeJS is for Moodle then we recommend that you set NodeJS version {{NodeJSExactVersion}} as your default version. You can do this by running:

nvm alias default {{NodeJSExactVersion}}

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

Once this is done, you can run the the following commands from your Moodle directory:

npm install

'''This may mention vulnerabilities, that's fine and doesn't apply.'''

npm install -g grunt-cli

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run [[Grunt]] in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Development mode (Moodle v3.10 and above) ==

All the above for Moodle 3.8 and up applies, plus (see MDLSITE-6130), any new Javascript module must be written on ES6.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

Note that, for Moodle 3.10 and up (see MDLSITE-6130), any new Javascript module must be written on ES6.

The call from a PHP file takes the same format
<code>
$PAGE->requires->js_call_amd('myplugin/myfile','myfunction');
</code>

And a minimal ES6 file will work with
<code>
export const init = () => {
window.console.log('we have been started');
};
</code>

=== Export default ===
There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

=== Inline Javascript ===
Another important note is that ES6 support is only for stand alone Javascript files because it relies on the compilation from Babel and Grunt. That means any inline Javascript (either in PHP or in Mustache templates) won't support the ES6 features. Instead it would be best to keep the inline Javascript as minimal as possible and only use it to load a stand alone Javascript module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== Troubleshooting ==

=== npm-shrinkwrap.json sha1 / sha512 changes ===

If grunt changes all the hashes in npm-shrinkwrap.json then try this:

rm -rf node_modules && npm i

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.
*MDL-67327 JavaScript issues when not following the official documentation, since Moodle 3.8

[[Category:AJAX]]
[[Category:Javascript]]

Question types

2020-10-06T20:50:10Z

2020-07-18T08:54:45Z

Marcusgreen:

VSCode stub
https://en.wikipedia.org/wiki/Visual_Studio_Code

VSCode is a an Integrated Development Environment from Microsoft available under the MIT License.
It works on Linux/Windows/OSX. It has a large number of plugins available, most entirely free/libre. It has good support
for Xdebug.

== Moodle specific Snippets and autocomplete (plugin) ==
https://marketplace.visualstudio.com/items?itemName=MateuszLesiak.vscode-moodle-snippets

Offers some useful Moodle specific code completion popups.

== Code Formatting (indentation) ==
https://marketplace.visualstudio.com/items?itemName=kokororin.vscode-phpfmt

== Show coding standards issues (plugin) ==
If you have Code Sniffer set up
https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Sniffs/Sniff.php
(or https://github.com/moodlehq/moodle-local_codechecker)
This plugin will show a wavy red line under code that does not conform.
https://github.com/wongjn/vscode-php-sniffer

== Run phpunit tests from within IDE (plugin) ==
https://marketplace.visualstudio.com/items?itemName=danilopolani.yet-another-phpunit

A file of unit tests or individual test can be run from within the IDE

== Generate PHP Doc blocks ==
Type /** at the top of the function and it grabs the parameters, including types if given and creates a PHPDoc block

https://marketplace.visualstudio.com/items?itemName=neilbrayfield.php-docblocker
== Auto trim trailing white space ==
To ensure trailing white space is trimmed do the following

Open VS User Settings (Preferences > Settings > User Settings tab).
Click the {} icon in the top-right part of the window. This will open a document.

Add a new "files.trimTrailingWhitespace": true setting to the User Settings document if it's not already there.
This is so you aren't editing the Default Setting directly, but instead adding to it.

Save the User Settings file.