MoodleDocs - User contributions [en]

Coding style

2017-07-31T09:37:10Z

Poltawski: /* If / else */

==Overview==
===Scope===

This document describes '''style''' guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

For details about using the Moodle API to get things done, see the [[Coding|coding guidelines]].

===Goals===

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness, such as use of method signatures, constants, and patterns that support IDE tools and auto-completion of method, class, and constant names.

When considering the goals above, each situation requires an examination of the circumstances and balancing of various trade-offs.

Note that much of the existing Moodle code may not follow all of these guidelines - we continue to upgrade this code when we see it.

===Useful tools===

There are a couple of different tools available to help you in writing code that conforms to this guide.

; Code checker (integrates with [https://github.com/moodlehq/moodle-local_codechecker/blob/master/README.md#ide-integration eclipse/phpstorm]): http://moodle.org/plugins/view.php?plugin=local_codechecker
; Marina Glancy's Moodle PHPdoc checker : https://github.com/marinaglancy/moodle-local_moodlecheck

It is worth using both tools to check the code you are writing as they both perform slightly different checks.
If you can get your code to pass both then you are well on the way to making friends with those who will be reviewing your work.

==File Formatting==

===PHP tags===

Always use "long" php tags. However, to avoid whitespace problems, DO NOT include the closing tag at the very end of the file.

<code php>
<?php

require('config.php');

</code>

===Indentation===

Use an indent of '''4 spaces''' with no tab characters. Editors should be configured to treat tabs as spaces in order to prevent injection of new tab characters into the source code.

Don't indent the main script level:

GOOD:
<code php>
<?php
require('config.php');
$a = required_param('a', PARAM_INT);
if ($a > 10) {
call_some_error($a);
} else {
do_something_with($a);
}
</code>

BAD:
<code php>
<?php
require('config.php');
$a = required_param('a', PARAM_INT);
if ($a > 10) {
call_some_error($a);
} else {
do_something_with($a);
}
</code>

SQL queries use special indentation, see [[SQL coding style]].

===Maximum Line Length===

The key issue is readability.

Aim for 132 characters if it is convenient, it is not recommended to use more than 180 characters.

The exception are string files in the <tt>/lang</tt> directory where lines <tt>$string['id'] = 'value';</tt> should have the value defined as a single string of any length, wrapped by quotes (no concatenation operators, no heredoc and no newdoc syntax). This helps to parse and process these string files without including them as a PHP code.

====Wrapping lines====

When wrapping a line, indent the follow-on line by 8 spaces rather than 4. For example:

<code php>
if (a_long_condition() &&
a_nother_long_condition()) {
do_something();
}
</code>

Using eight spaces makes it easier to spot the difference between wrapped lines and indented blocks.

The example above is only an illustration; it is best practice to avoid wrapping lines in control structures. See below.

====Wrapping Arrays====

Associative arrays are a exception to the rule about 8-space indent for follow-on lines. The correct layout is:
<code php>
$plugininfo['preferences'][$plugin] = array(
'id' => $plugin,
'link' => $pref_url,
'string' => $modulenamestr
);
</code>
Lining up the =>s is optional. Small arrays can be done on one line.

====Wrapping function declarations====
If you have many parameters, indent them in line with the first parameter:
<code php>
public function graded_users_iterator($course, $grade_items = null, $groupid = 0,
$sortfield1 = 'lastname', $sortorder1 = 'ASC',
$sortfield2 = 'firstname', $sortorder2 = 'ASC') {
</code>

====Wrapping Control Structures====
If you have too many conditions in one control structure, try setting some variables before the start of the structure to improve readability.

GOOD:
<code php>
$coursecategory = ($element['object']->is_course_item() or $element['object']->is_category_item());
$scalevalue = in_array($element['object']->gradetype, array(GRADE_TYPE_SCALE, GRADE_TYPE_VALUE));

if ($coursecategory and $scalevalue) {
</code>

BAD:
<code php>
if (($element['object']->is_course_item() or $element['object']->is_category_item())
and ($element['object']->gradetype == GRADE_TYPE_SCALE
or $element['object']->gradetype == GRADE_TYPE_VALUE)) {
</code>

===Line Termination===

Use standard '''Unix''' text format. Lines must end only with a linefeed (LF). Linefeeds are represented as ordinal 10, or hexadecimal 0x0A.

Do not use carriage returns (CR) like old ''Macintosh'' computers (0x0D).

Do not use the carriage return/linefeed combination (CRLF) as ''Windows'' computers (0x0D, 0x0A).

Lines should not contain trailing spaces. In order to facilitate this convention, most editors can be configured to strip trailing spaces, such as upon a save operation. However, if you are editing an existing Moodle file and are planning to submit your changes for integration, please switch off that feature so that whitespace changes do not pollute the patch (other developers will have trouble viewing what you've done if every other line has been edited for whitespace).

==Naming Conventions==

===Filenames===

Filenames should :
* be whole english words
* be as short as possible
* use lowercase letters only
* end in .php, .html, .js, .css or .xml

===Classes===

Class names should always be lower-case English words, separated by underscores:

<code php>
class some_custom_class {
function class_method() {
echo 'foo';
}
}
</code>

Always use () when creating new instances even if constructor does not need any parameters.

<code php>
$instance = new some_custom_class();
</code>

When you want an plain object of no particular class, for example when you are preparing some data to insert into the database with $DB->insert_record, you should use the PHP standard class '''stdClass'''. For example:

<code php>
$row = new stdClass();
$row->id = $id;
$row->field = 'something';
$DB->insert_record('table', $row);
</code>

''Before Moodle 2.0, we used to define a class '''object''' extending stdClass, and use new object(); This has now been deprecated. Please use stdClass instead.''

===Functions and Methods===

Function names should be simple English lowercase words, and start with the [[Frankenstyle]] prefix and plugin name to avoid conflicts between plugins. Words should be separated by underscores.

Verbosity is encouraged: function names should be as illustrative as is practical to enhance understanding.

Note there is no space between the function name and the following (brackets).

<code php>
function block_course_overview_get_overviews(array $courses) {

// Actual function code goes here.
}
</code>

There is an exception for [[Activity modules|activity modules]] that still use only plugin name as the prefix for legacy reasons.

<code php>
function forum_set_display_mode($mode = 0) {
global $USER, $CFG;

// Actual function code goes here.
}
</code>

====Function Parameters====

Parameters are always simple lowercase English words (sometimes more than one, like $initialvalue), and should always have sensible defaults if possible.

Use "null" as the default value instead of "false" for situations like this where a default value isn't needed.
<code php>
public function foo($required, $optional = null)
</code>

However, if an optional parameter is boolean, and its logical default value should be true, or false, then using true or false is acceptable.

===Variables===

Variable names should always be easy-to-read, meaningful lower-case English words. If you really need more than one word then run them together, but keep them short as possible. Use '''plural''' names for arrays of objects. Use '''positive''' variables names always (allow, enable not prevent, disable).

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)
GOOD: $allowfilelocking = false

BAD: $Quiz
BAD: $camelCase
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string
BAD: $preventfilelocking = true

Core global variables in Moodle are identified using uppercase variables (ie $CFG, $SESSION, $USER, $COURSE, $SITE, $PAGE, $DB and $THEME). Don't create any more!

===Constants===

Constants should always be in upper case, and always start with [[Frankenstyle]] prefix and plugin name (in case of activities the module name only for legacy reasons). They should have words separated by underscores.
<code php>
define('BLOCK_COURSE_OVERVIEW_SHOWCATEGORIES_NONE', '0');
define('FORUM_MODE_FLATOLDEST', 1);
</code>

===Booleans and the null value===

Use lower case for '''true''', '''false''' and '''null'''.

=== Namespaces ===

Namespaces are not required for any new code and there is no requirement to move non-namespaced classes to namespaces. If
namespaces are used - they must conform to these rules.

Classes belonging to a namespace must be created in a classes directory inside a plugin (e.g. mod/forum/classes), or for core code,
in lib/classes or subsystemdir/classes.

The classname and filename for all namespaced classes must conform to the
[[Automatic class loading|automatic class loading]] rules.

Use at most one namespace declaration per file.

GOOD:
<code php>
<? // This is a file mod/porridge/classes/local/equipment/spoon.php

namespace mod_porridge\local\equipment;

class spoon {
// Your code here.
}

// End of file.
</code>

BAD:
<code php>
namespace mod_porridge\local\equipment;

class spoon {
// Your code here.
}

namespace mod_porridge\local\procedures; // We are changing the namespace here, do not do it.

class eat {
// Another code here.
}

// End of file.
</code>

The namespace declaration may be preceded with a doc block.

The [[Coding style#Classes|class naming]] rules also apply to the names for each level of namespace.

The namespace declaration must be the first non-comment line in the file, followed by one blank line, followed by the (optional)
"use" statements, one per line, followed by one blank line.

"use" statements should be used to avoid repetition of long namespaces in the code.

Do not import an entire namespace with a "use" statement, import individual classes only.

Do not use named imports ("use XXX as YYY;") unless it is absolutely required to resolve a conflict.

GOOD:
<code php>

use mod_porridge\local\equipment\spoon; // One class per line.
use mod_porridge\local\equipment\bowl; // One class per line.

</code>

BAD:
<code php>

use mod_porridge\local\equipment\spoon, mod_porridge\local\equipment\bowl; // Multiple classes per line.
use mod_porridge\local; // Importing an entire namespace.
use core; // Importing an entire namespace.
use mod_breakfast; // Importing an entire namespace.
use mod_porridge\local\equipment\spoon as silverspoon; // Named import with no good reason.

</code>

Never use the __NAMESPACE__ magic constant.

Never use the "namespace" keyword anywhere but the namespace declaration.

BAD:
<code php>
$obj = new namespace\Another();
</code>

Do not use bracketed "namespace" blocks.

BAD:
<code php>
namespace {
// Global scope.
}
</code>

Namespaces MUST only be used for classes existing in a subfolder of "classes".

For new classes - the maximum level of detail should be used when deciding the namespace.

GOOD:
<code php>
namespace xxxx\yyyy; // xxxx is the component, yyyy is the api.

class zzzz {
}
</code>

Never use a leading backslash (\) in "namespace" and "use" statements.

Global functions called from namespaced code should never use a leading
backslash (\). Classes from outside the current scope use the leading backslash
or are imported by the "use" keyword. See
[http://www.php.net/manual/en/language.namespaces.fallback.php PHP manual] for
details.

GOOD:
<code php>
namespace mod_breakfast\local;

use moodle_url;

echo get_string('goodmorning', 'mod_breakfast'); // No leading backslash for global functions.
$url = new moodle_url(...); // Leading backslash not needed here because we imported it into our namespace via "use".
$tasks = \core\task\manager::get_all_scheduled_tasks(); // Leading slash needed here.
$a = new \stdClass(); // Leading slash needed here.
</code>

BAD:
<code php>
namespace \mod_breakfast; // The leading backslash should not be here.

use \core\task\manager; // The leading backslash should not be here.

\get_string('xxxx', 'yyyy'); // The leading backslash should not be here.
</code>

==== Parts of a namespace ====

Given the following fully qualified name of a class:

"\<level1>\<level2>\<level3>\...\<classname>"

There are clear rules for what is allowable at each level of namespace. Only the first level is mandatory. Nested namespaces are used when the class implements some core API or when the plugin maintainer want to organise classes to separate namespaces within the plugin - see rules regarding the level2 for details.

==== Rules for level1 ====

The first level MUST BE EITHER:
* a full component name (e.g. "\mod_forum"). All classes using namespaces in a plugin MUST be contained in
this level 1 namespace.
or
* "\core" for all core apis

==== Rules for level2 ====

The second level, when used, MUST BE EITHER:
* The short name of a core API (must be defined on https://docs.moodle.org/dev/API). The classes in this namespace must either implement or use the API in some way.
or
* "\local" for any other classes in a component, if the maintainer wants to organise them further (note that for most components, it's probably enough to have all their own classes in the root level1 namespace only).

==== Rules for level3 ====

There are no rules limiting what can be used as a level 3 namespace. This is where a plugin or addon can make extensive use of
namespaces with no chance of conflict with any other plugin or api, now and forever onwards.

==== Examples ====

GOOD:
<code php>
namespace mod_breakfast; // Plugin's own namespace when not using nested namespaces (typical)
namespace mod_breakfast\local; // Plugin's own namespace when using nested namespaces
namespace mod_breakfast\local\utils; // Plugin's own namespace when using nested namespaces with further organisation
namespace mod_breakfast\event; // Plugin's namespace to implement core API

</code>

BAD:
<code php>
namespace mymodule; // Violates the level1 rules - invalid component name
namespace mod_breakfast\myutilities; // Violates the level2 rules - invalid core API name
</code>

== Strings ==

Since string performance is not an issue in current versions of PHP, the main criteria for strings is readability.

===Single quotes===

Always use single quotes when a string is literal, or contains a lot of double quotes (like HTML):

<code php>
$a = 'Example string';
echo '';
$html = '<a href="http://something" title="something">Link</a>';
</code>

===Double quotes===

These are a lot less useful in Moodle. Use double quotes when you need to include plain variables or a lot of single quotes.

<code php>
echo "$string";
$statement = "You aren't serious!";
</code>

Complex SQL queries should be always enclosed in double quotes.

<code php>
$sql = "SELECT e.*, ue.userid
FROM {user_enrolments} ue
JOIN {enrol} e ON (e.id = ue.enrolid AND e.enrol = 'self' AND e.customint2 > 0)
JOIN {user} u ON u.id = ue.userid
WHERE :now - u.lastaccess > e.customint2";
</code>

===Variable substitution===

Variable substitution can use either of these forms:

<code php>
$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";
</code>

===String concatenation===

Strings must be concatenated using the "." operator.

<code php>
$longstring = $several.$short.'strings';
</code>

If the lines are long, break the statement into multiple lines to improve readability. In these cases, put the "dot" at the end of each line.

<code php>
$string = 'This is a very long and stupid string because '.$editorname.
" couldn't think of a better example at the time.";
</code>
The dot operator may be used without any space to either side (as shown in the above examples), or with spaces on each side; whichever the developer prefers.

===Language strings===

====Capitals====

Language strings should "Always look like this" and "Never Like This Example".

Capitals should only be used when:
# starting a sentence, or
# starting a proper name, like Moodle.

====Structure====

Strings should not be designed for UI concatenation, as it may cause problems in other languages. Each string should stand alone.

BAD:
$string['overduehandling'] = 'When time expires';
$string['overduehandlingautosubmit'] = 'the attempt is submitted automatically';
$string['overduehandlinggraceperiod'] = 'there is a grace period in which to submit the attempt, but not answer more questions';
$string['overduehandlingautoabandon'] = 'that is it. The attempt must be submitted before time expires, or it is not counted';

GOOD:
$string['overduehandling'] = 'Time expiry behaviour';
$string['overduehandlingautosubmit'] = 'Unfinished attempts will be auto-submitted immediately';
$string['overduehandlinggraceperiod'] = 'Unfinished attempts have a short grace period to be submitted for grading';
$string['overduehandlingautoabandon'] = 'Unfinished attempts are immediately discarded';

==Arrays==

===Numerically indexed arrays===

When declaring indexed arrays with the array function, a trailing space must be added after each comma delimiter to improve readability:

<code php>
$myarray = array(1, 2, 3, 'Stuff', 'Here');
</code>

Multi-line indexed arrays are fine, but pad each successive lines as above with an 8-space indent:

<code php>
$myarray = array(
1, 2, 3, 'Stuff', 'Here',
$a, $b, $c, 56.44, $d, 500);
</code>

===Associative arrays===

Use multiple lines if this helps readability. For example:

<code php>
$myarray = array(
'firstkey' => 'firstvalue',
'secondkey' => 'secondvalue'
);
</code>

==Classes==

=== Class declarations ===

* Classes must be named according to Moodle's naming conventions.
* The brace should always be written on the line beside the class name.
* Every class must have a documentation block that conforms to the PHPDocumentor standard.
* All code in a class must be indented with 4 spaces.
* Placing additional code in class files is permitted but discouraged. In such files, two blank lines must separate the class from any additional PHP code in the class file.

: An example:

<code php>
/**
* Documentation Block Here
*/
class sample_class {
// All contents of class
// must be indented 4 spaces.
}
</code>

===Class member variables===

Member variables must be named according to Moodle's variable naming conventions.

Any variables declared in a class must be listed at the top of the class, above the declaration of any methods.

The var construct is not permitted. Member variables always declare their visibility by using one of the '''private''', '''protected''', or '''public''' modifiers. Giving access to member variables directly by declaring them as public is permitted but discouraged in favor of accessor methods (set/get).

==Functions and methods==
===Function and method declaration===

Functions must be named according to the Moodle function naming conventions.

Methods inside classes must always declare their visibility by using one of the private, protected, or public modifiers.

As with classes, the brace should always be written on same line as the function name.

Don't leave spaces between the function name and the opening parenthesis for the arguments.

The return value must not be enclosed in parentheses. This can hinder readability, in additional to breaking code if a method is later changed to return by reference.

Return should only be one data type. It is discouraged to have multiple return types

<code php>
/**
* Documentation Block Here
*/
class sample_class {

/**
* Documentation Block Here
*/
public function sample_function() {
// All contents of function
// must be indented four spaces.
return true;
}
}
</code>

===Function and method usage===

Function arguments should be separated by a single trailing space after the comma delimiter.

<code php>
three_arguments(1, 2, 3);
</code>

===Magic methods===
Magic methods are heavily discouraged, justification will be required when used. Note: lazyness will not be a valid argument.

(See MDL-52634 for discussion of rationale)

==Control statements==

In general, use white space liberally between lines and so on, to add clarity.

===If / else===

Put a space before and after the control statement in brackets, and separate the operators by spaces within the brackets. Use inner brackets to improve logical grouping if it helps.

Indent with four spaces.

''Don't use elseif!''

Always use braces (even if the block is one line and PHP doesn't require it). The opening brace of a block is always placed on the same line as its corresponding statement or declaration.

<code php>
if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}
</code>

===Switch===

Put a space before and after the control statement in brackets, and separate the operators by spaces within the brackets. Use inner brackets to improve logical grouping if it helps.

Always indent with four spaces. Content under each case statement should be indented a further four spaces.

<code php>
switch ($something) {
case 1:
break;

case 2:
break;

default:
break;
}
</code>

===Foreach===

As above, uses spaces like this:

<code php>
foreach ($objects as $key => $thing) {
process($thing);
}
</code>

===Ternary Operator===

The ternary operator is only permitted to be used for '''short''', '''simple to understand''' statements. If the statement can't be understood in one sentance, use an if statement instead.

Whitespace must be used around the operators to make it clear where the operation is taking place.

GOOD:
<code php>
$username = isset($user->username) ? $user->username : '';
</code>

BAD:
<code php>
$toload = (empty($CFG->navshowallcourses))?self::LOAD_ROOT_CATEGORIES:self::LOAD_ALL_CATEGORIES;
$coefstring = ($coefstring=='' or $coefstring=='aggregationcoefextrasum') ? 'aggregationcoefextrasum' : 'aggregationcoef';
</code>

==Require / include==

Each file that is accessed via browser should start by including the main config.php file.

<code php>
require(__DIR__ . '/../../config.php');
</code>

Any other include/require should use a path starting with <tt>_DIR_</tt> or an absolute path starting with <tt>$CFG->dirroot</tt> or <tt>$CFG->libdir</tt>. Relative includes starting with "../" can [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP], so should not be used. Our [[CLI scripts]] must not use relative config.php paths starting with "../".

For library files in normal usage, require_once should be used (this is different from config.php which should always use 'require' as above). Examples:
<code php>
require_once(_DIR_ . '/locallib.php');
require_once($CFG->libdir . '/filelib.php');
</code>

Includes should generally only be done at the top of files or inside functions/methods that need them. Using include/require in the middle of a file in global scope very hard to audit the security of the code.

All other scripts with the exception of imported 3rd party libraries should use following code at the very top to prevent direct execution which might reveal error messages on misconfigured production servers.

<code php>
defined('MOODLE_INTERNAL') || die();
</code>

==Documentation and comments==

Code documentation explains the code flow and the purpose of functions and variables. Use it whenever practical.

===PHPDoc===

Moodle stays as close as possible to "standard" [http://www.phpdoc.org/ PHPDoc format] to document our files, classes and functions. This helps IDEs (like Netbeans or Eclipse) work properly for Moodle developers, and also allows us to generate web documentation automatically.

PHPDoc has a number of tags that can be used in different places (files, classes and functions). We have some particular rules for using them in Moodle that you must follow:

====Types====

Some of the tags below (@param, @return...) do require the specification of a valid php type and a description. All these are allowed:

* PHP primitive types: int, bool, string...
* PHP complex types: array, stdClass (not Array, object).
* PHP classes:full or relative (to current namespace) class names.
* true, false, null (always lowercase).
* static: for methods returning a new instance of the child/caller class.
* self: for methods returning a new instance of the parent/called class.
* $this: for methods returning the current instance of the class.
* void: for methods with a explicit empty "return" statement.

Also, there are some basic rules about how to use those types:
* We use [http://php.net/manual/en/language.types.type-juggling.php short type names] (bool instead of boolean, int instead of integer).
* When multiple occurrences of a given "type" are used, it's highly recommended to document them as type[] instead of the simpler and less informative "array" alternative.
* When multiple different types are possible, they must be separated by a vertical bar (pipe).
* All primitives and keywords must be lowercase. The case of the complex types and classes must match the original.

====Tags====

===== @copyright =====

These include the year and copyright holder (creator) of the original file. Do not change these in existing files!

@copyright 2008 Kim Bloggs

===== @license =====

These must be GPL v3+ and use this format:

@license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

===== @param =====

Don't put hyphens or anything fancy after the variable name, just a space.

@param [[#Types|type]] $name Description.

===== @return =====

The @return tag is mandatory if the function has a return statement, but can be left out if it does not have one.

The description portion is optional, it can be left out if the function is simple and already describes what is returned.

@return [[#Types|type]] Description.

===== @var =====

The @var tag is used to document class properties.

@var [[#Types|type]] Description.

Exceptionally, when none of the available [[#Types|types]] define the returned value, inline @var phpdocs (within the body of the methods) providing type hinting are allowed to the returned type. Don't abuse!

===== @uses =====

If a function uses die or exit, please add this tag to the docblock to help developers know this function could terminate the page:

@uses exit

===== @access =====

The access can be used to specify access control for an element

# Should only be used when the method definition does not already specify access control.
# In the case of functions, specifying public access is redundant and so should be avoided.

@access private

===== @package =====

The package tag should always be used to label php files with the correct [[Frankenstyle]] component name. Full rules are explained on that page, but in summary:

# If the file is part of any component plugin, then use the plugin component name (eg '''mod_quiz''' or '''gradereport_xls''')
# If the file is part of a core subsystem then it will be core_xxxx where xxxx is the name defined in get_core_subsystems(). (eg '''core_enrol''' or '''core_group''')
# If the file is one of the select few files in core that are not part of a subsystem (such as lib/moodlelib.php) then it just as a package of '''core'''.
# Each file can only be part of ONE package.

(We do not have standards for @subpackage at all. You can use within your @package how you like.)

@package gradereport_xls

===== @category =====

We use @category only to highlight the public classes, functions or files that are part of one of our [[Core APIs]], or that provide good example implementations of a Core API. The value must be one of the ones on the [[Core APIs]] page.

@category preferences

===== @since =====

When adding a new classes or function to the Moodle core libraries (or adding a new method to an existing class), use a @since tag to document which version of Moodle it was added in. For example:

@since Moodle 2.1

===== @see =====

If you want to refer the user to another related element (include, page, class, function, define, method, variable) then you can use @see.

@see some_other_function()

===== @link =====

If you want to refer the user to an external URL, use @link.

@link https://docs.moodle.org/dev/Core_APIs

===== inline @link =====

Occasionally you might want to refer to something else inline within your text, say in a function description. For these cases you can use an inline @link (with an element name OR a URL) and it looks like this:

/**
* This function uses {@link get_string()} to obtain the currency names...
* .....

===== @deprecated (and @todo) =====

When deprecating an old API, use a @deprecated tag to document which version of Moodle it was deprecated in, and add @todo and @see if possible. Make sure to mention relevant MDL issues. For example:

<code php>
/**
* ...
* @deprecated since Moodle 2.0 MDL-12345 - please do not use this function any more.
* @todo MDL-22334 This will be deleted in Moodle 2.2.
* @see class_name::new_function()
*/
</code>

If it is important that developers update their code, consider also adding a debugging('...', DEBUG_DEVELOPER); call to repeat the deprecated message. If the old function can no longer be supported at all, you may have to throw a coding_exception. There are examples of the various options in lib/deprecatedlib.php.

===== @throws =====

This tag is valid and can be used optionally to indicate the method or function will throw and exception. This is to help developers know they may have to handle the exceptions from such functions.

===== Other specific tags =====

There are some tags that are only allowed within some contexts and not globally. More precisely:

* @Given, @When, @Then, within the [[Acceptance testing#Adding steps definitions|behat steps definitions]].
* @dataProvider (and some more coming, see MDLSITE-2824), within [[Writing PHPUnit tests#Generators|unit tests]].

===Files===

All files that contain PHP code should contain, without any blank line after the php open tag, a full GPL copyright statement at the top, plus a SEPARATE docblock right under it containing a:

# short one-line description of the file
# longer description of the file
# @package tag (required)
# @category tag (only when everything in the file is related to one of the [[Core APIs]])
# @copyright (required)
# @license (required)

<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* This is a one-line short description of the file.
*
* You can have a rather longer description of the file as well,
* if you like, and it can span multiple lines.
*
* @package mod_mymodule
* @category backup
* @copyright 2008 Kim Bloggs
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

===Classes===

All classes must have a complete docblock like this:

<code php>
/**
* Short description for class.
*
* Long description for class (if any)...
*
* @package mod_mymodule
* @copyright 2008 Kim Bloggs
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

(NOTE that classes that are fundamental to core APIs will also need a @category tag)

The exception are files containing only one class and nothing else. In that case the class is covered by the file docblock and adding an explicit class docblock is optional.

===Properties===

All properties should have a docblock with the following minimum information:

<code php>
class example {
/** @var string This variable does something */
protected $something;
}
</code>
or
<code php>
class example {
/**
* This variable does something and has a very long description which can
* wrap on multiple lines
* @var string
*/
protected $something;
}
</code>
Even if there are several properties all sharing something in common, do not use [https://en.wikipedia.org/wiki/PHPDoc#DocBlock_Templates DocBlock templates]. Instead, document every property explicitly as in the following example:

<code php>
class zebra {
/** @var int The number of white stripes */
protected $whitestripes = 0;

/** @var int The number of black stripes */
protected $blackstripes = 0;

/** @var int The number of red stripes */
protected $redstripes = 0;
}
</code>

===Constants===

Class constants should be documented in the following way:

<code php>
class sam {
/**
* This is used when Sam is in a good mood.
*/
const MOOD_GOOD = 0;
}
</code>

===Functions===

All functions and methods should have a complete docblock like this:

<code php>
/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* use @see as below. If it's useful to link to Moodle
* documentation on the web, you can use a @link below or also
* inline like this {@link https://docs.moodle.org/dev/something}
* Then, add descriptions for each parameter and the return value as follows.
*
* @see clean_param()
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return bool A status indicating success or failure
*/
</code>

You must include a description even if it appears to be obvious from the @param and/or @return lines.

An exception is made for overridden methods which make no change to the meaning of the parent method and maintain the same arguments/return values. In this case you should omit the comment completely. Use of the @inheritdoc or @see tags is explicitly forbidden as a replacement for any complete docblock.

===Defines===

All defines should be documented in the following way:

<code php>
/**
* PARAM_INT - integers only, use when expecting only numbers.
*/
define('PARAM_INT', 'int');

/**
* PARAM_ALPHANUM - expected numbers and letters only.
*/
define('PARAM_ALPHANUM', 'alphanum');
</code>

===Inline comments===

Inline comments must use the "// " (2 slashes + whitespace) style, laid out neatly so that it fits among the code and lines up with it. The first line of the comment must begin with a capital letter (or a digit, or '...') and the comment must end with a proper punctuation character. Permitted final characters are '.', '?' or '!'.

<code php>
function forum_get_ratings_mean($postid, $scale, $ratings = null) {
if (!$ratings) {

$ratings = array(); // Initialize the empty array.

$rates = $DB->get_records('forum_ratings', array('post' => $postid));

// ... then process each rating in
// turn.
foreach ($rates as $rate) {
do_something_with($rate);
}

// Do we need to tidy up?
if (!empty($rates))
// 42 more things happen here!
finsh_up();
}
</code>

GOOD:
<code php>
// Comment explaining this piece of code.
</code>
BAD:
<code php>
/* Comment explaining this piece of code. */
# Comment explaining this piece of code.
// comment explaining this piece of code (without capital letter and punctuation)
</code>

If your comment is due to some MDL issue, please feel free to include the correct MDL-12345 in your comment. This makes it easier to track down decisions and discussions about things.

====Using TODO====

This is especially important if you know an issue still exists in that code that should be dealt with later. Use a TODO along with a MDL code to mark this. For example:

<code php>
// TODO MDL-12345 This works but is a bit of a hack and should be revised in future.
</code>

If you have a big task that is nearly done, apart a few TODOs, and you really want to mark the big task as finished, then you should file new tracker tasks for each TODO and change the TODOs comments to point at the new issue numbers.

(The script .../lib/simpletest/todochecker.php in Moodle 2.0 will check this. Requires an admin login. This is a new requirement, see MDL-19772)

===CVS keywords===

We have stopped using CVS keywords such as $Id$ in Moodle 2.0 completely.

==Exceptions==

Use exceptions to report errors, especially in library code.

Throwing an exception has almost exactly the same effect as calling print_error, but it is more flexible. For example, the caller can choose to catch the exception and handle it in some way. It also makes it easier to write unit tests.

Any exception that is not caught will trigger an appropriate call to print_error, to report the problem to the user.

Do not abuse exceptions for normal code flow. Exceptions should only be used in erroneous situations.

===Exception classes===

We have a set of custom exception classes. The base class is moodle_exception. You will see that the arguments you pass to new moodle_exception(...) are very similar to the ones you would pass to print_error. There are more specific subclasses for particular types of error.

To get the full list of exception types, search for the regular expression 'class +\w+_exception +extends' or ask your IDE to list all the subclasses of moodle_exception.

Where appropriate, you should create new subclasses of moodle_exception for use in your code.

A few notable exception types:
; moodle_exception : base class for exceptions in Moodle. Use this when a more specific type is not appropriate.
; coding_exception : thrown when the problem seems to be caused by a developer's mistake. Often thrown by core code that interacts with plugins. If you throw an exception of this type, try to make the error message helpful to the plugin author, so they know how to fix their code.
; dml_exception (and subclasses) : thrown when a database query fails.
; file_exception : thrown by the File API.

==Dangerous functions and constructs==
PHP includes multiple questionable features that are highly discouraged because they are very often source of serious security problems.

# do not use ''eval()'' function - language packs are exception (to be solved in future).
# do not use ''preg_replace()'' with /e modifier - use callbacks in order to prevent unintended PHP execution.
# do not use backticks for shell command execution.
# do not use ''goto'', neither the operator neither labels - use other programming techniques to control the execution flow.

==Policy about coding-style only fixes==

Way before this coding-style guide was defined and agreed, a lot of code had been written already. Obviously such code does not follow the coding-style at all. While '''we enforce conformance for all the new code''', we are not paranoid about the status of all the previous one.

In any case, in order to normalize the (progressive, non-critical) transition, a policy issue (MDL-43233) was created and agreed about. And these are the rules to apply to coding-style only changes:

# Related coding-style changes (same lines, a variable within a method/function, adjacent comments...) within a real issue are allowed.
# Unrelated coding-style changes (other methods, blocks of code, comments...) within a real issue are only accepted for master and in a separate commit.
# Coding-style only issues are only accepted for master along the first 2 months of every cycle.

== Git commits ==

Constructing a clear and informative commit is an important aspect of the craft of creating open source code and the history of commits is a vital part of the communication between developers. Time should be spent on crafting commits appropriately and using the git tools to achieve it.

Git commits should:

* Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.
* Include the MDL-xxxx issue number associated with the change
* Include CODE AREA when appropriate. (Code area, is just a short name for the area of Moodle that this change affects. It can be a component name if that makes sense, but does not have to be. Remember that your audience here is humans not computers, so if a shortened version of a component name is more readable and distinctive, use that instead.)
* Be formatted as:
<pre>
MDL-xxxx CODE AREA: short summary (72 chars soft limit)

Blank line on line 2, followed by an unlimited length detailed explanation
following if necessary. This section might include the motivation for the change
and contrast it with the previous behaviour.
</pre>

Git commits should not:
* Include changes from bugs found and fixed before integration
* Include many separate revisions to the same lines of code for a single issue
* Arbitrarily split when part of a atomic set of logical changes

For more guidance, see [[Commit cheat sheet]]

==Credits==

This document was drawn from the following sources:

# The original [https://docs.moodle.org/en/index.php?title=Development:Coding&oldid=53799 Coding guidelines] page
# The [http://framework.zend.com/manual/en/coding-standard.html Zend guidelines] and
# Feedback from all core Moodle developers

==See also==

* [[Javascript/Coding_Style|Javascript Coding Style]]
* [[CSS_Coding_Style|CSS Coding Style]]
* [[SQL coding style]]
* [[Coding]]
* [[CodeSniffer]]
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code Checker plugin]
* [[Accessibility#Moodle-related_accessibility_coding_guidelines|Accessibility coding guidelines]]

[[Category:Coding guidelines|Coding style]]

Javascript/Coding Style

2017-06-12T14:21:25Z

Poltawski: MDL-57139: Promises guidance

The Moodle JavaScript coding style

== Overview ==

This document outlines the exceptions to the general Moodle [[Coding_style|Coding style]] which apply to JavaScript.

Unless otherwise specified, developers should follow the general coding style for advice on coding style.

=== Goals ===

Consistent coding style is important in any development project, and
particularly when many developers are involved. A standard style helps to
ensure that the code is easier to read and understand, which helps overall
quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness

== Naming conventions ==

=== Variable and function naming ===

Contrary to the standard Moodle coding style, camelCase should be used to name variables and functions in JavaScript.

==== Correct ====
<code javascript>
var currentY,
courseCategory,
lastValue,
lastBackgroundColor;

function doSomething() {
// Do stuff here.
}

function doSomethingElse() {
// Do stuff here.
}

var someFunction = function() {
// Do stuff here.
};
</code>

==== Incorrect ====
<code javascript>
var current_y,
currenty,
course_category,
coursecategory,
last_value,
lastvalue,
last_background_color,
lastbackgroundcolor;

function dosomething() {
}

function do_something_else() {
}

var somefunction = function() {
};

var some_other_function = function() {
};

var somevalue = null;

if (someTest) {
somevalue = function() {
return (something && complicated || somethingelse);
};
} else {
somevalue = 'basicvalue';
}

</code>

=== Class naming ===

Classes should be named using CamelCase starting with an uppercase
letter.

This helps to clearly separate variables, and standard functions from those
used to create a new instance.

==== Correct ====
<code javascript>
// The instantiator:
function Pantry() {
// Setup code goes here.
}

// Making use of it:
var myPantry = new Pantry();

// And another:
function PantryShelf() {
}

var myPantryShelf = new PantryShelf();
</code>

==== Incorrect ====
<code javascript>
// There is no distinction here between a normal function, and one used to
// create a new object:
function pantry() {
}

// This results in an unclear object creation:
var myPantry = new pantry();

// This one is also incorrect, despite using camelCase:
function pantryShelf() {
}
var myPantryShelf = new pantryShelf();

// This one is also incorrect:
function pantry_shelf() {
}
var myPantryShelf = new pantry_shelf();
</code>

=== Constants ===

Variables intended to be constants should use the same naming style of ALL UPPERCASE.

Constants are recommended for use in the following scenarios:
* CSS: An object containing any CSS classes you may wish to use with Nodes; and
* SELECTORS: An object containing query selectors for selecting Nodes.

Generally, the keys under this object should also be capitalised.

==== Example ====
<code javascript>
var CSS = {
MYCLASS: 'myclass',
YOURCLASS: 'yourclass'
},
SELECTORS = {
MYNODES: 'div.example .myclass',
YOURNODES: 'div.example .yourclass'
};

function anExampleFunction() {
theNode = Y.one(SELECTORS.MYNODES)
.addClass(CSS.YOURCLASS)
.removeClass(CSS.MYCLASS);
}
</code>

== Variables ==

All variables must:
* be declared before they are used and using the <tt>var</tt> keyword;
* be declared once, and only once, for the scope in which they are used;
* only be declared if they are to be used; and
* use sensible naming, following the naming convention.

=== Method call wrapping ===

When wrapping a long line which consists of a chained series of functions,
break the line at the end of each function, and continue the next chain on
a new line.

The line should be indented by spaces.

The start of each line should contain the concatanation character, and the
final line should contain a trailing semicolon.

==== Correct ====
<code javascript>
var childNode = Y.Node.create('<div />')
.addClass(CSS.SOMECLASS)
.setAttribute('someAttribute', 'someValue')
.appendTo(parentNode);
</code>

==== Incorrect ====
<code javascript>
// All on one line:
var childNode = Y.Node.create('<div />').addClass(CSS.SOMECLASS).setAttribute('someAttribute', 'someValue').appendTo(parentNode);

// A mix of separation and line concatanation:
var childNode = Y.Node.create('<div />').addClass(CSS.SOMECLASS)
.setAttribute('someAttribute', 'someValue').appendTo(parentNode);

// The concatanation character is at the end of the line:
var childNode = Y.Node.create('<div />').
addClass(CSS.SOMECLASS).
setAttribute('someAttribute', 'someValue').
appendTo(parentNode);
</code>

== Whitespace ==

=== Operators ===

There should be a space at either side of '''all''' binary operators to help improve
legibility of code. This includes:
* =
* &&
* ||
* ===
* +
* -
* /
* *

There should be no space around unary operators. This includes:
* !
* ++
* --

There should be no space around the function operator (.)

==== Correct ====
<code javascript>
// Valid binary operators:
var a = 1,
b = (a && 1),
c = (b || 1),
d = (b === c),
e = Y.Node.create('<div>Some Content</div>');

// No space around the . operator when it's not a continuation:
e.someFunctionCall();

// Whitespace is allowed for a function operator when it is a continuation starting on a new line:
e.someFunction()
.someOtherFunction()
.someFinalFunction();

// Unary operators should not be separated by whitespace:
a = a++;
b = b--;
c = (!e.someResult());

// An example bringing most of these together:
var index,
loopTest = 0;
for (index = 0; (!loopTest <= (a / b * (c + d - e.getValue()))); index++) {
loopTest = index * 12;
}

</code>

==== Incorrect ====
<code javascript>
var a=1,
b= (a&&1),
c =(b||1),
d = (b===c);

a = a ++;
b =b++;
c= c++;
d = d++ ;

var e = Y . Node . create('<div>Some content</div>');

for ( index = 0;index<a; index ++ ) {
}
</code>

=== Assignment ===
In the case of object property assignment, there should be a space after
the colon, but not before.

==== Correct ====
<code javascript>
var anObject = {
someKey: 'someValue',
anotherKey: Y.one(SELECTORS.FOO)
};
</code>

==== Incorrect ====
<code javascript>
var anObject = {
// Incorrect because a space is present both before and after the assignation character:
someKey : 'someValue',

// Incorrect because there is no whitespace either side of the assignation character:
anotherKey:Y.one(SELECTORS.FOO)
};
</code>

== Documentation and comments ==

Modules should be documented using the standard YUI guidance: http://yui.github.io/yuidoc/syntax/index.html.

=== General notes ===

* Unless otherwise specified, comments should conform to the general style guidelines;
* all comments must start with leading whitespace before the first word on each line; and
* all indentation must be in addition to any existing leading whitespace on the line.

=== Official documentation ===

All JavaScript documentation must:
* use the correct docblock format;
* use the correct JavaScript types where relevant (note, Int is not a valid type in JavaScript);
* use all appropriate tags;
* produce valid documentation using the YUIDoc toolset;
* have a linebreak between the description and the list of tags.

Note:

YUIDoc will only generate documentation for docblocks starting with /**.

YUIDoc will try to generate documentation for *all* docblocks starting /**.

==== Correct ====

<code javascript>
/**
* This docblock describes a YUI module.
*
* @module moodle-mod_food-marmite
*/

/**
* This docblock describes the marmite class within the
* moodle-mod_food-marmite module.
*
* @class Marmite
*/

/**
* This is an example docblock comment. It describes a function called
* marmite.
*
* It adds a number of jars of marmite to the cupboard.
*
* @method addMarmite
* @param {Number} [jarCount=1] The number of jars of marmite to add to the
* cupboard. This parameter is optional and defaults to 1.
* @chainable
*/

/**
* This docblock describes the property weight, in grams.
*
* @property weight
* @type {Number}
* @default '500'
*/

/**
* This docblock describes an attribute.
*
* @attribute weight
* @type {Number}
* @default '500'
*/
</code>

==== Incorrect ====

<code javascript>
/*
* This is an invalid comment block. It wouldn't be picked up by yuidoc as
* the comment style is incorrect.
*
* @method foo
*/

// This is also an invalid comment block and wouldn't be picked up by
// YUIDoc.

/**
* Although this style would be picked up by YUIDoc, it is hard to read.
*
* @method foo
*/

/**
*Although this style would be picked up by YUIDoc, it is also hard to read.
*
*@method foo
*/

/**
* This docblock is mostly valid but does not include a linebreak between
* the description, and the tags.
* @method foo
*/
</code>

=== General comments ===

All shorter comments, for example those explaining the subsequent few lines of code should use the // style of comments.

Comments not intended for official documentation must *not* use the Docblock style of commenting as YUIDoc will attempt to include the comment in official documentation.

==== Correct ====

<code javascript>
// This is a valid set of comments for one line.

// And this is a valid longer comment to describe the subsequent few lines
// in as much detail as required. It can consist of multiple sentences, as
// long as each new line starts with the correct comment style.
</code>

==== Incorrect ====

<code javascript>
/* This is an invalid comment style for short comments. */

//This is also an invalid style as there is no leading whitespace after the
//comment indicator.

/**
* This is an invalid multi-line comment. Multi-line comments should not
* use the docblock style comments unless they are a valid and fully
* formatted docblock.
*/

/*
* This is an also invalid multi-line comment. Although it is not a full
* docblock style, it does not start with the // style of comment
* indicator.
*/
</code>

== Promises ==
Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
// Single promise chain:
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});

// Need the result of two promises at once:
$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});
});

return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

== See Also ==

* [[Coding_style|Coding Style]]
* [[CSS_Coding_Style|CSS Coding Style]]
* [[Coding]]

[[Category:Coding guidelines]]
[[Category:Javascript]]

User talk:Poltawski/Javascript promises

2017-06-12T14:21:06Z

Poltawski: MDL-57139

== Promises ==
Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
// Single promise chain:
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});

// Need the result of two promises at once:
$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});
});

return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:19:22Z

Poltawski: /* Correct */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
// Single promise chain:
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});

// Need the result of two promises at once:
$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});
});

return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:19:00Z

Poltawski: /* Incorrect */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
// Single promise chain:
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});

// Result of two promises:
$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});
});

return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:17:57Z

Poltawski: /* Correct */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
// Single promise chain:
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});

// Result of two promises:
$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:17:23Z

Poltawski: /* Correct */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
str.get_string('title')
.then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
actionitem.find('.icon').replaceWith(pixhtml);
return;
});

$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:13:24Z

Poltawski: /* Correct */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
$.when(Str.get_string('competencypicker', 'tool_lp'), renderPromise())
.then(function(title, html) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:09:10Z

Poltawski: /* Correct */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp');
}).then(function(title) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
return;
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:07:12Z

Poltawski: /* Incorrect */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp');
}).then(function(title) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notification.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T14:06:37Z

Poltawski: /* Chain rather than nest */

== Promises ==

Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operate and introduce bugs which only expose themselves in asynchronous edge cases (see article [https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html we have a problem with promises]). To encourage promise usage to be more understandable, consistent and avoid edge case bugs, we have adopted best practices suggested by Nolan Lawson and verified by [https://github.com/xjamundx/eslint-plugin-promise eslint-plugin-promise].

=== Always return or throw ===

When writing promises they must:
* return another promise, or
* return a synchronous value (or undefined), or
* throw a synchronous error

==== Correct ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
return templates.renderPix(image, 'core', title);
}).then(function(pixhtml) {
$('#selector').html(pixhtml);
makeUIVisible();
return;
});
</code>

==== Incorrect ====
<code javascript>
str.get_strings(stringRequests).then(function(title) {
templates.renderPix(image, 'core', title).function(pixhtml) {
$('#selector').html(pixhtml);
});
}).then(function() {
// Wrong because renderPix() has not guaranted to be resolved here.
makeUIVisible();
});
</code>

=== Chain rather than nest ===

Promises as are a construct which help prevent the pyramid of doom and regain linear control flow and error handling. They should not be nested.

* Promises should be chained rather than nested.
* $.when() should be used to deal with the result of multiple promises

==== Correct ====
<code javascript>
renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp');
}).then(function(title) {
self._popup = new Dialogue(title, html);
});
</code>

==== Incorrect ====

<code javascript>
return renderPromise().then(function (html) {
return Str.get_string('competencypicker', 'tool_lp').then(function(title) {
self._popup = new Dialogue(title, html);
});
});
</code>

=== Avoid mixing callbacks and promises ===
Avoid mixing callbacks and promises. Design code to embrace promise-y patterns for asynchronous code to make maximum use of promises.

==== Correct ====
<code javascript>
function doWork(input) {
return renderPromise();
}

doWork(input).then(function () {
$('#selector').html(html);
}).catch(Notification.exception);
</code>

==== Incorrect ====
<code javascript>
function doWork(input, successHandler, errorHandler) {
renderPromise().then(function (html) {
successHandler(html)
}).catch(errorHandler);
}

doWork(input, function () {
$('#selector').html(html);
}, function (error){
Notificatin.exception(error);
});
</code>

User talk:Poltawski/Javascript promises

2017-06-12T13:53:01Z

Poltawski: /* Do not nest */

User talk:Poltawski/Javascript promises

2017-06-12T13:52:39Z

Poltawski: /* Do not nest */

User talk:Poltawski/Javascript promises

2017-06-12T13:49:10Z

Poltawski: /* Do not nest */

User talk:Poltawski/Javascript promises

2017-06-12T13:42:08Z

Poltawski: /* Incorrect */

User talk:Poltawski/Javascript promises

2017-06-12T13:41:26Z

Poltawski: /* Do not nest */

User talk:Poltawski/Javascript promises

2017-06-12T13:39:04Z

Poltawski: /* Correct */

User talk:Poltawski/Javascript promises

2017-06-12T13:38:45Z

Poltawski: /* Correct */

User talk:Poltawski/Javascript promises

2017-06-12T13:38:31Z

Poltawski: /* Incorrect */

User talk:Poltawski/Javascript promises

2017-06-12T13:37:38Z

Poltawski:

User talk:Poltawski/Javascript promises

2017-06-12T13:35:56Z

Poltawski: /* Promises */

User talk:Poltawski/Javascript promises

2017-06-01T10:14:52Z

Poltawski: /* Promises */

User talk:Poltawski/Javascript promises

2017-06-01T09:59:36Z

Poltawski: Created page with " == Promises == Promises are used extensively in modern Moodle Javascript APIs to handle asynchronous situations. It is unfortunately common to misunderstand how they operat..."

NPM

2017-06-01T09:04:45Z

Poltawski: /* Switching NPM versions */

{{Work in progress|forumurl=https://tracker.moodle.org/browse/MDL-52250}}
NPM is a package manager for JavaScript. It is used by Moodle developers to install a number of cli tools, primarily those related with [[Grunt]].

== npm dependency management ==
Tools installed by npm include things like our css/js compressors, post-processors and integrity checks. As differences in output from these tools would cause different results for different developers working on the same code, we need to ensure installed packages are the same.

=== npm shrinkwrap ===
We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run `npm install`. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5.

=== Updating npm dependencies ===
Periodically we will update our npm dependencies, the process for doing this is:

# Ensure you use npm >= 5 - node version 8 (see MDL-59094 for details of why we require this version)
# Run <pre>npm install packages-name@version</pre> (e.g. <pre>npm install eslint@3.8.0</pre>)
# Verify that both the package.json and npm-shrinkwrap.json have been updated
# Commit to source control

=== NPM versions ===

In general, you will get the best results when using the latest stable NPM version for install node dependencies with Moodle.

==== Switching NPM versions ====
We have discovered upstream npm bugs (MDL-59103) when upgrading NPM version with a previously installed node_modules directory. It is recommended to clear the node_modules directory and re-running `npm install` when changing npm version to avoid these problems.

NPM

2017-06-01T09:04:18Z

Poltawski:

{{Work in progress|forumurl=https://tracker.moodle.org/browse/MDL-52250}}
NPM is a package manager for JavaScript. It is used by Moodle developers to install a number of cli tools, primarily those related with [[Grunt]].

== npm dependency management ==
Tools installed by npm include things like our css/js compressors, post-processors and integrity checks. As differences in output from these tools would cause different results for different developers working on the same code, we need to ensure installed packages are the same.

=== npm shrinkwrap ===
We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run `npm install`. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5.

=== Updating npm dependencies ===
Periodically we will update our npm dependencies, the process for doing this is:

# Ensure you use npm >= 5 - node version 8 (see MDL-59094 for details of why we require this version)
# Run <pre>npm install packages-name@version</pre> (e.g. <pre>npm install eslint@3.8.0</pre>)
# Verify that both the package.json and npm-shrinkwrap.json have been updated
# Commit to source control

=== NPM versions ===

In general, you will get the best results when using the latest stable NPM version for install node dependencies with Moodle.

==== Switching NPM versions ====
We have discovered upstream npm bugs (MDL-59103) when upgrading NPM version with a previously installed node_modules directory. It is recommended to clear the node_modules directory and re-installing when changing npm version to avoid these problems.

NPM

2017-06-01T08:56:50Z

Poltawski: /* npm shrinkwrap */

NPM

2017-06-01T08:56:38Z

Poltawski: /* npm shrinkwrap */

{{Work in progress|forumurl=https://tracker.moodle.org/browse/MDL-52250}}
NPM is a package manager for JavaScript. It is used by Moodle developers to install a number of cli tools, primarily those related with [[Grunt]].

== npm dependency management ==
Tools installed by npm include things like our css/js compressors, post-processors and integrity checks. As differences in output from these tools would cause different results for different developers working on the same code, we need to ensure installed packages are the same.

=== npm shrinkwrap ===
We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run <pre>npm install</pre>. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5.

=== Updating npm dependencies ===
Periodically we will update our npm dependencies, the process for doing this is:

# Ensure you use npm >= 5 - node version 8 (see MDL-59094 for details of why we require this version)
# Run <pre>npm install packages-name@version</pre> (e.g. <pre>npm install eslint@3.8.0</pre>)
# Verify that both the package.json and npm-shrinkwrap.json have been updated
# Commit to source control

NPM

2017-06-01T08:56:23Z

Poltawski: /* npm shrinkwrap */

{{Work in progress|forumurl=https://tracker.moodle.org/browse/MDL-52250}}
NPM is a package manager for JavaScript. It is used by Moodle developers to install a number of cli tools, primarily those related with [[Grunt]].

== npm dependency management ==
Tools installed by npm include things like our css/js compressors, post-processors and integrity checks. As differences in output from these tools would cause different results for different developers working on the same code, we need to ensure installed packages are the same.

=== npm shrinkwrap ===
We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run <code>npm install</code>. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5.

=== Updating npm dependencies ===
Periodically we will update our npm dependencies, the process for doing this is:

# Ensure you use npm >= 5 - node version 8 (see MDL-59094 for details of why we require this version)
# Run <pre>npm install packages-name@version</pre> (e.g. <pre>npm install eslint@3.8.0</pre>)
# Verify that both the package.json and npm-shrinkwrap.json have been updated
# Commit to source control

NPM

2017-05-31T09:23:44Z

Poltawski: Updated npm section for npm version 5 changes (much simpler)

Integration Review

2017-05-09T08:43:18Z

Poltawski: /* During continuous integration/Freeze/QA period */

==Purpose==

The purpose of the integration review is to:
* Ensure consistent quality across the codebase
* Ensure that pedagogical aims of Moodle are at the forefront of any change
* Take into consideration the holistic view of moodle, looking at the impact beyond where the original developer was focused
* Provide guidance and feedback to developers, helping them learn and improve
* Consider '''other perspectives''' of other users perhaps not considered by original developers e.g.
** Teachers
** Students
** Administrators
**Third-party developers

==Integration Review Process==

# Run automated pre-checks against the continuous integration server. (In future this can be automated and also moved into a publicly accessible domain.)
# Final code review, much like the peer review, except that this is the final check. To include
## Takes place in-situ (integrated) to examine the impact to other integrated issues
## Checking against the coding guidelines - syntax/whitespace
## Moodleisms - using the built-in API functions where appropriate
## Cross-DB compatibility
## Security
# Check purpose - the patch needs to fix the issue reported.
# Verify target branches are appropriated. They must match 100% the rules defined for [[#Backporting|backporting issues]].
# Ensure backwards compatibility is maintained. As a starting point backwards compatibility must always be maintained. Where backwards compatibility is affected it should be:
## Well discussed with evidence of justification
## Documented and communicated to the community
# Verify that components are correct and check the right people have been involved (e.g. component maintainers)
# For fundamental changes, check that a thread has been started in an appropriate forum, and other Moodlers, given enough time to comment.
# Tests - must be written to guide tester to verify the fix is working.
## Unit test - very much preferred if applicable
## at end of Wednesday, ensure testing is going to complete as expected. else take other actions (speak to test manager)
# Performance - we have to look at maintaining optimum code here, as far as simple patches that can affect performance. (simple optimisations)
# Scalability - if master only - we're looking far future, stable branches may not be lucky to get such improvements.
# git authorship is correct vs committer + credits due are mentioned + email addresses
# Documentation / PHP Doc / readability
# [[Tracker_issue_labels]] which might need adding. Particularly:
## docs_required / dev_docs_required / release_notes: About which type of documentation is required for the issue.
## ui_change / api_change: About the implications of the change.
## unit_test_required / acceptance_test_required / qa_test_required: About the need to cover the issue with some test.
# Fixed Version after integration - is the versions that the issue is patched for. (A rule here: mention master if its the only branched fixed. If not, don't mention master)
# Update the workflow counters
## If an issue is in need of a second review +1 to errors column in integration workflow counters

== Integration Principles ==

Integration (non-technical but philosophical) principles (4-5 words determining if something has to be integrated/backported or no):

# safety: if something does not look safe, stable, it won't land. Be conservative.
# security: all security issues, if not breaking principle (1) will be integrated/backported to all security-supported versions.
# community: Anything not useful for the community (or against it) won't be integrated/backported. We can measure the community as 10%HQ, 10%Partners, 10%Core developers, 20%Admins, 20%Teachers, 30%Students - not exact science, just one approximation, you know). Question yourself how the change will affect those groups and ensure positives are bigger always (only affected groups count). All community issues, if not breaking principles (1) and (2) will be integrated.
# typology: bug fixes will be always integrated/backported to all the supported braches if none of the principles (1), (2) and (3) are violated. Also, partially-unsupported branches can receive some if they are important enough. Improvements and new features go, exclusively, to master only, that's the main reason for short release periods. We *must* not make exceptions to this.
# priority: issues will be "ordered down" by priority down (where priority is a [https://tracker.moodle.org/issues/?filter=14000 mix of various factors], dynamic). And will be integrated in that order. If something has to be delayed, better if it is low priority. Once again, nothing here can break any of the previous principles.
# tests: unit tests and acceptance tests will backported as far as possible without breaking (1) and (2). New features required to implement tests will be backported if the API is 100% backwards compatible.
If all the principles are fulfilled, the answer for "should I integrate this?" is, "yes, please!"
(apart from technical findings, of course, that can lead to the issue being not integrated/reopened at last, these principles are 100% philosophical)

==Schedule==
===In normal periods ===
The integrators adhere to the following schedule:

* Sunday 22:00 UTC: Issues waiting for integration brought into current integration.
* Monday: Integration
* Tuesday: Integration
* Wednesday: [[Testing of integrated issues#The testing process|Testing]]. Integrators duties during this time are to monitor, facilitate and 'problem solve' the testing process.
* Thursday: Testing should be completed by 07:00 UTC, at which time remaining testing failures will be reverted and reopened. The release process follows.
* Friday: Should be kept free from integration. Integration systems are maintained during this time.

=== During continuous integration/Freeze/QA period ===
During the continuous integration period the integration team are continuously focused on producing regular builds of master to facilitate QA and fast fixes to issues identified.

* Throughout:
** Issues are picked on a one by one basis, prioritising [https://docs.moodle.org/dev/QA_testing#Resetting_tests QA blockers] and master regressions (MUST FIX) issues.
** Any non bug fix issues are given the ''integration_held'' label and are explicitly not picked for integration. Still, anybody is able to add a reasoned ''unhold_requested'' label to those issues in order to get them unblocked by the development managers. Note this does not guarantee the issue to land before release, but just gives it a chance to be integrated like any other issue.
** Our goal is to achieve 'releaseability' throughout, so we stop integrating to ensure a release happens

So, basically, once the QA cycle begins (4 weeks before release) and until release, we do organize work as follows:
* Continuous officially begins. Everybody is on integration. Until end of on-sync period.
* Monday: Integration and [[Testing of integrated issues#Differences in test process during continuous integration periods|testing]] happens.
* Tuesday: Integration happens until 12:00 (UTC+8), [[Testing of integrated issues#Differences in test process during continuous integration periods|afterwards we try to achieve 100% 'Test Passed']] and stop integrating any untested changes until a master release is produced.
* Wednesday: [Assuming a master release has been rolled] Integration and testing continues
* Thursday: Integration and testing continues
* Friday: Integration happens until 12:00 (UTC+8), afterwards we try to achieve 100% 'Test Passed' and stop integrating any untested changes until a master release is produced.

Note: along this period we always release as many stable weeklies as master rolls (on-demand, beta, rc) happen (see MDLSITE-3470). Note that those tags are not simply tags but they come with some important implications, aiming to stability, safety and clarity. Integrators will try to remain loyal to them, be warned:

* Once beta is released... new features or improvements "unrelated" with the release will be really harder to be accepted. A +4 from developer managers (normally +3 is enough) will be needed to proceed with the issue. Integrators vote will be, always, -1.
* Once rc are released... new features or improvements "unrelated" with the release are forbidden. No unhold voting, no managers. Simply forbidden.
* Last week before release, only "related" issues will be picked for integration. Everything else (bug fixes included) are kept out if unrelated, at very least until after release. No distractions.
Definition: "related": said to be a followup of required to release, planned OR security issue.

=== On-sync period ===
Immediately after a major release and for a short period (right now, 3 weeks, matching HQ sprint duration), the integration team is under the named on-sync period.

At all effects, it's a normal period (see above), and weeklies are produced for supported stable branches and also for master. But with one important rule/goal:

* We must keep the latest stable branch and master 100% on-sync, specifically about versions and upgrade steps.

This simple, but important constraint, is there to facilitate the integration of impeding bugs, needing urgent resolution, and by keeping them the same, we guarantee that any stable or master fix will apply without problems to both branches. Of course, in order to achieve the rule, these must be also observed along the period:

* We continuously perform diffs between the latest stable and master, controlling that we are on-sync. Any non-authorised difference is cleaned (rewritten).
* Both improvements and new features (and, in general, everything leading to divergence) are held until the on-sync period ends.

Last, but not less important, a second goal for this on-sync period is:

* The environmental requirements '''for next major version''' [[Release process#3_weeks_after|must be agreed and resolved so they can land to master]] early in the process, remaining defined and stable over the next, 6 months of, development cycle.

== Backporting ==

Whilst we'd all like all Moodle users to be using our latest and greatest code, there is a balance to strike between improving our software and maintaining stability (both in terms of regressions, but also training and documentation materials). Large amounts of change on the stable branches make the lives difficult for institutions to manage upgrades between point releases.

==== General policy ====
Our general policy is as follows:

* Bug fixes will be backported to all (and only to) supported stable branches.
** When fixing a bug, please provide a fix for all supported stable branches.
** If a fix doesn't make sense to be backported to every branch, please make it clear in the issue.
* Improvements or new features will only land in master.

==== Process for requesting a non bug-fix backport ====
Improvements or new features can be requested to be backported to the stable branches. We urge developers to consider this request carefully. In recent years, Moodle has moved to a short and predicatable time based release schedule and we use a very effective distributed source control system. Both of these process changes should ensure that a change not being backported to the stable branches is not as problematic as it may have used to be.

Should you feel that a new feature or improvement needs backporting, please follow this process:

# File a new issue.
# Set the issue title using our backport template guide. (i.e. "Fix forum alignment (backport of MDL-99999)") - see [https://docs.moodle.org/dev/Tracker_guide#Tracker_fields Tracker_guide]
# Link the original issue
# You should include clear rationale for the request to backport

The integration team will process backport requests, with the following guidelines:
# The integration team will together consider each request individually considering the needs of the community (influenced by forum posts, moodle partners, nagging developers etc).
# Backports will happen not earlier than 3 weeks and not later than 2 months after the issue has landed in master.
# Rationale will be given for rejection

If the backport request is approved, please follow the usual development process to submit the feature or improvement on earlier branches.

==== Polite note about bug classification ====
Many issues can be appropiately classified as borderline bugfix/improvements. We politely request that developers do not try and 'game the system' by clasifying their improvements as bugs intentionally. If your fix is in a grey area, please state your case for it being a bug fix clearly. The integration team will use their discretion where necessary.

==== Backport fixes to unsupported branches ====
* Given the [[#General policy|general policy]] above, only supported stable branches are candidates normally.
* Also security and dataloss issues are accepted to be fixed into security-only supported branches.
* Apart from the previous, backport to unsupported branches only will happen when the issue is a '''direct regression caused by a bug fix''' introduced by the latest releases. This applies to both security-only and out-of-support branches. A new weekly release will be performed including the fix.

== Fixing issues identified during integration review/ testing ==

When a branch has been merged by an integrator, it is important that you do not modify the existing history of your branch (e.g. by amending or squashing your commits) and instead add new commits on top. If you modify the history of your branch, it makes it extremely difficult for the integrator to merge your changes (and see the differences).

As a general rule, this means that if your issue has entered the 'in integration review' stage of the development process, please only add new commits on top of your existing commits. There are circumstances when your issue will be 'in integration review' but not merged (and thus possible to squash changes) but if in any doubt, please add new commits and ask the integrator to squash your changes for you.

== Commit squashing ==

The Integration team will sometimes recommend squashing commits when things do not look natural (and may offer to do this for you), especially when there are "fix-commits" in the history happening before integration. But [https://moodle.org/local/chatlogs/index.php?conversationid=13987#c489485 our policy] is "if you want your history of commits to look like bad, it's your history". You will not be forced to squash your changes. You should pay close attention to https://docs.moodle.org/dev/Coding_style#Git_commits and intend to "Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.".

Acceptance testing/Compatibility changes

2017-05-04T08:25:25Z

Poltawski: /* And I follow "Course 1" */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
Summary
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
|-
|After
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
|}
Why did this change?

UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===

Summary
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
|-
|After
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>
|}
Why did this change?

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
 Summary 
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1" And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
|-
|After
|<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants"
</code>
|}
 Why did this change? 

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:25:10Z

Poltawski: /* And I navigate to "Participants" node in "My courses > C1" */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
Summary
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
|-
|After
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
|}
Why did this change?
UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===

Summary
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
|-
|After
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>
|}
Why did this change?

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
 Summary 
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1" And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
|-
|After
|<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants"
</code>
|}
 Why did this change? 

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:24:28Z

Poltawski: /* And I click on "Edit settings" "link" in the "Administration" "block" */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
Summary
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
|-
|After
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
|}
Why did this change?
UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===

Summary
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
|-
|After
|<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>
|}
Why did this change?

The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
 Summary 
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1" And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

 Examples 

Before:
<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
After:
<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants"
</code>

 Why did this change? 
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:23:50Z

Poltawski: /* And I follow "Course 1" */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
Summary
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

{| class="wikitable"
|-
|+Examples
|-
|Before
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
|-
|After
|<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
|}
Why did this change?
UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===

Summary
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
Examples

Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

Why did this change?
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
 Summary 
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1" And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

 Examples 

Before:
<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
After:
<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants"
</code>

 Why did this change? 
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:17:28Z

Poltawski:

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
Summary
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

Examples

Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>

Why did this change?
UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===

Summary
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}
Examples

Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

Why did this change?
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
 Summary 
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1" And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

 Examples 

Before:
<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
After:
<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants"
</code>

 Why did this change? 
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:12:13Z

Poltawski: /* Moodle 3.2 */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

==== Examples ====
Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
==== Why did this change? ====
UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

=== And I navigate to "Participants" node in "My courses > C1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I navigate to "Participants" node in "My courses > C1" And I navigate to "Site blogs" node in "Site pages"
|-
|New step/s
| And I navigate to course participants
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "student1"
And I follow "Course 1"
And I navigate to "Participants" node in "Current course > C1"
</code>
After:
<code>
Scenario: Going to course participants
When I log in as "student1"
And I follow "Course 1"
And I navigate to course participants"
</code>

==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:07:38Z

Poltawski:

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

==== Examples ====
Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
==== Why did this change? ====
UI changes in the new dashboard mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes.
== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:07:02Z

Poltawski: Undo revision 52228 by Poltawski (talk)

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

==== Examples ====
Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

==== Why did this change? ====
UI Changes mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:06:39Z

Poltawski: /* Compatibility changes */

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

==== Why did this change? ====
UI Changes mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Browsers

2017-05-04T08:02:30Z

Poltawski:

This page complements [[Acceptance testing]] providing info about how to run the acceptance tests suite in different browsers.

== Drivers ==

There are Selenium drivers (http://docs.seleniumhq.org/projects/webdriver/) to run acceptance tests in different browsers:

* Firefox - https://code.google.com/p/selenium/wiki/FirefoxDriver
* Chrome - https://code.google.com/p/selenium/wiki/ChromeDriver
* Safari - https://code.google.com/p/selenium/wiki/SafariDriver
* Internet Explorer - https://code.google.com/p/selenium/wiki/InternetExplorerDriver
* Microsoft Edge - https://www.microsoft.com/en-us/download/details.aspx?id=48212
* PhantomJS (Webkit) - http://phantomjs.org/
* IPhone - https://code.google.com/p/selenium/wiki/IPhoneDriver

Each driver should be downloaded and Selenium .jar should be started specifying the path to the driver; depending on the driver there could be other requirements.

=== PhantomJS ===

PhantomJS is different as it is a headless browser as it is quite faster than other drivers, it doesn't need a GUI to run and can execute JS, it doesn't even need to be used through Selenium (you can do it though, but it's not officially supported) and you can do it

* Download PhantomJS: http://phantomjs.org/download.html
* /path/to/your/phantomjs/bin/phantomjs --webdriver=4444

Note that 4444 is the default port used by Selenium so you must specify another one if you want to run them together and specify the port in $CFG->behat_config.

=== Examples ===

# Selenium in Linux (firefox by default + chrome)
java -jar /opt/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/opt/chromedriver

# Selenium in OSx (firefox & safari by default + chrome)
java -jar /Users/moodle/Downloads/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/Users/moodle/Downloads/chromedriver

# Selenium in Windows (started using git bash) (firefox by default + chrome + internet explorer)
java -jar /c/seleniumdrivers/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/c/seleniumdrivers/chromedriver.exe -Dwebdriver.ie.driver=/c/seleniumdrivers/IEDriverServer.exe

# PhantomJS
/path/to/your/phantomjs/bin/phantomjs --webdriver=4444

== Compatibility ==
Not all the drivers can execute all of Moodle's step definitions; we tagged the step definitions that are using features not supported by all browsers and also limitations that some browsers have; refer to the following table to know which browsers can run which tags:

{| class="wikitable"
|
|File uploads (@_file_upload)
|Browser dialogs (@_alert)
|Switch window (@_switch_window)
|Switch frame (@_switch_iframe)
|Bug in phantomjs (@_bug_phantomjs)
|-
|Firefox
|Yes
|Yes
|Yes
|Yes
|Yes
|-
|Chrome
|Yes
|Yes
|Yes
|Yes
|Yes
|-
|Internet Explorer
|Yes
|Yes
|No
|Yes
|Yes
|-
|Safari
|Yes
|No
|No
|Yes
|Yes
|-
|PhantomJS
|No
|No
|Yes
|Yes
|No
|}

== Working combinations of OS+Browser+selenium ==
As OS, Browsers and Selenium keeps updating, some combination of OS+Browser+Selenium will not work on specific moodle version.

We try to support the latest version of these combinations but they are not always BC and hence may not work with older releases. Please refer to [[Acceptance testing/Browsers/Working combinations of OS+Browser+selenium]] to ensure you have correct combination of them to run acceptance test.

[[Category:Quality Assurance]]

Running acceptance test

2017-05-04T08:02:13Z

Poltawski: /* Tests are failing */

== 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 or --parallel''' (required) Number of parallel behat run to initialise
# '''-m or --maxruns''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun''' (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 or --add-core-features-to-theme''' (optional) Since Moodle 3.2. Use this option to add all core features to specified theme's (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>
<code>
php admin/tool/behat/cli/run.php
</code>

=== Parallel runs ===
For running parallel runs, use following command
<code>
php admin/tool/behat/cli/run.php
</code>
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)
# '''-a or --add-core-features-to-theme''' (optional) Since Moodle 3.2. Use this option to add all core features to specified theme's (comma separated list)
# 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"'''

=== 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" window''' 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 -a option. For example, '''-a {THEME_NAME}'''

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

=== Running acceptance tests with different browser ===
By default behat will run with Firefox browser through Selenium. By adding the following code to your config.php you can change the selected browser that is run when behat is invoked. You will need to run php admin/tool/behat/cli/init.php for changes to take effect. Then use --profile='chrome'.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>
[[Acceptance_testing/Browsers|More info about alternative browsers]]

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

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

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

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

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

=== 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.'''

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat

[[Category:Quality Assurance]]

Running acceptance test

2017-05-04T08:01:33Z

Poltawski:

== 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 or --parallel''' (required) Number of parallel behat run to initialise
# '''-m or --maxruns''' (optional) Max parallel site which should be initialised at one time. If your system is slow, then you can initialise sites in chucks.
# '''--fromrun''' (optional) Initialise site to run specified run from. Used for running acceptance tests on different vms
# '''--torun''' (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 or --add-core-features-to-theme''' (optional) Since Moodle 3.2. Use this option to add all core features to specified theme's (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>
<code>
php admin/tool/behat/cli/run.php
</code>

=== Parallel runs ===
For running parallel runs, use following command
<code>
php admin/tool/behat/cli/run.php
</code>
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)
# '''-a or --add-core-features-to-theme''' (optional) Since Moodle 3.2. Use this option to add all core features to specified theme's (comma separated list)
# 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"'''

=== 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" window''' 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 -a option. For example, '''-a {THEME_NAME}'''

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

=== Running acceptance tests with different browser ===
By default behat will run with Firefox browser through Selenium. By adding the following code to your config.php you can change the selected browser that is run when behat is invoked. You will need to run php admin/tool/behat/cli/init.php for changes to take effect. Then use --profile='chrome'.

<code>
$CFG->behat_profiles = array(
'chrome' => array(
'browser' => 'chrome',
'tags' => '@javascript',
)
);
</code>
[[Acceptance_testing/Browsers|More info about alternative browsers]]

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

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

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

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

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

=== 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.'''

== External links ==
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:01:18Z

Poltawski:

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

==== Examples ====
Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

==== Why did this change? ====
UI Changes mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

[[Category:Quality Assurance]]

Acceptance testing/Compatibility changes

2017-05-04T08:00:32Z

Poltawski:

As new features are developed for Moodle, some UI changes can cause changes which unfortunately affect behat feature files. This page is intended to document important compatibility changes for behat test developers.

= Compatibility changes =
== Moodle 3.3 ==

=== And I follow "Course 1" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I follow "Course 1"
|-
|New step/s
|And I am on "Course 1" course homepage And I am on "Course 1" course homepage with editing mode on
|-
|Backported to:
|Moodle 3.1.6, 3.2.3 and up.
|}

==== Examples ====
Before:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on site homepage
And I follow "Course 1"
Then I should see "Topic 1"
</code>
After:
<code>
Scenario: I am on the course homepage
When I log in as "student1"
And I am on "Course 1" course homepage
Then I should see "Topic 1"
</code>
==== Why did this change? ====
The boost theme changes how navigation works and the new steps are compatible with boost and bootstrap based themes

== Moodle 3.2 ==
=== And I click on "Edit settings" "link" in the "Administration" "block" ===
==== Summary ====
{| class="wikitable"
|-
|Previous step/s:
| And I click on "Edit settings" "link" in the "Administration" "block"
|-
|New step/s
|And I navigate to "Edit settings" in current page administration
|-
|Backported to:
|Moodle 3.2.1, 3.1.4 and up.
|}

==== Examples ====
Before:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I follow "Course 1"
When I click on "Edit settings" "link" in the "Administration" "block"
</code>
After:
<code>
Scenario: Going to course settings
When I log in as "teacher1"
And I am on "Course 1" course homepage
When I navigate to "Edit settings" in current page administration
</code>

==== Why did this change? ====
UI Changes mean the existing 'loose' step matches multiple values. The replacement step should help speed up your tests.

== Moodle 3.1 ==
=== Behat migration from 2.5 to 3.x ===
Behat 3 brings a lot of extensibility and modularity but there are compatibility changes for running tests and writing step definitions. See [[Acceptance testing/Migrating from Behat 2.5 to 3.x in Moodle]] for fully details when coming from earlier versions of Moodle.

= See also =
* [[Running_acceptance_test]]

Acceptance testing/Compatibility changes

2017-05-04T07:59:38Z

Poltawski: Undo revision 52221 by Poltawski (talk)

Acceptance testing/Compatibility changes

2017-05-04T07:59:16Z

Poltawski:

Acceptance testing/Compatibility changes

2017-05-04T07:57:37Z

Poltawski: /* Behat migration from 2.5 to 3.x */

Acceptance testing/Compatibility changes

2017-05-04T07:57:08Z

Poltawski: /* Moodle 3.1 */

Acceptance testing/Compatibility changes

2017-05-04T07:54:26Z

Poltawski: /* Moodle 3.2 */

Acceptance testing/Compatibility changes

2017-05-04T07:54:12Z

Poltawski: /* Why did this change? */