MoodleDocs - User contributions [en]

Conditional activities

2021-10-22T19:08:19Z

Kordan: /* Custom completion */

{{Moodle_2.0}}
= Design document =
(This is a design document by sam marshall from the Open University. It is based on earlier discussion in this wiki, and then detailed discussion with moodle.com staff who contributed improvements and corrections.)

See MDL-15497 for tasks and tracking.

sam marshall, 21 May 2008; updated as of 26 June 2008. Exported to MediaWiki format using OpenOffice.org 3.0 beta (i.e. this page doesn't perfectly represent the word-processor version) and manually tweaked a bit to fix it where it was obviously wrong.
== Introduction ==
This design document describes in some detail a proposed method to add support for ‘conditional activities’ to Moodle. It is based on a [https://docs.moodle.org/en/Development:Conditional_activities discussion on the Moodle wiki], conversations with Moodle.com staff, and only the teeniest pinch of OU requirements. 

This is divided into two related, but separate, chunks of work.
=== Completion tracking ===
Make the system store whether or not an activity has been ‘completed’.

This may be according to an activity-specific definition of completion, or because the student has ticked a box saying they’ve finished it.

When tracked automatically, completion could vary from formal requirements such as ‘scoring 90% on this quiz’ to informal requirements intended to ensure participation such as ‘post at least 3 times on this forum’.

It should be possible for teachers to access progress information for their students, so that they can see if anyone is falling behind.
=== Conditional availability ===
Allow or prevent access to an activity depending on various conditions.

These conditions may include the completion of other activities; in the case of graded activities, also whether the grade was pass/fail, or a specific amount. It also may include date.
=== Development process ===
I will do this work here. It is possible that time constraints might mean I only do the first part (completion tracking).

Development will be against Moodle 1.9, because we need it here at the OU, but it will never actually be committed into Moodle 1.9. The code will instead be ported to Moodle 2.0, which will require various changes (particularly in the area of database access).

Code will be PHP5. We will primarily test against Postgres here but intend using standard Moodle database API and only simple SQL where needed, so database compatibility is unlikely to be a problem.

In some cases the OU have versions of these features. I will be coding automatic upgrade from the previous versions. This will not be included in the core Moodle 2.0 version.
== Completion tracking ==
=== Completion options ===
The completion system can be enabled or disabled at site, course, and activity level.
* At site level, the new admin variable $CFG->enablecompletion (defaults to 1?).
* At course level, a new mdl_course field enablecompletion (defaults to 1).
* At activity level, a new mdl_course_modules field completion with values 0 = none, 1 = manual (student decides when they’ve completed something), 2 = automatic. Defaults to 1 but may be set by module e.g. a quiz module could default to automatic, label could set it to 0 so you don’t get checkboxes beside each label, etc.
This table illustrates the effect of these options. (‘enablecompletion’ is abbreviated to ‘ec’.)

{| class="prettytable"
| '''Location'''
| '''Feature'''
| '''Appears if'''
|-
| Admin settings
| On-off toggle for $CFG->ec
| –
|-
| Course settings
| On-off toggle for course ec
| $CFG->ec
|-
| Activity settings
| Off/manual/automatic option for course-module completion
| $CFG->ec && course ec
|-
| Course view
| Completion display/controls against activity
| $CFG->ec && course ec && completion
|-
| Admin block
| Link to progress report
| $CFG->ec && course ec && user has permission
|}
=== Completion states and conditions ===
Completion state is stored per-user for every activity. There are four states:
* <nowiki>Not completed [default – not stored in database]</nowiki>
* Completed (pass/fail unspecified)
* Completed, passed
* Completed, failed
The final two states only apply when completion is based on a specific grade result. These are used only in some situations. Here are the rules:
* Grade visible, ‘grade to pass’ set: ‘completed, passed’ and ‘completed, failed’ states will be used.
* ‘Grade to pass’ not set ''or''grade is hidden ''or''grade is hidden-until (regardless of until date): only the standard ‘not completed’, ‘completed’ states are used.
This is a ‘push’ system – the state is not computed live but is saved and that value used. When completion for the activity is set to manual, students can toggle this value between not completed and completed. When it is set to automatic, the system adjusts the value in certain cases.
==== Standard conditions ====
There are two standard conditions which do not require (much) module-specific behaviour.
* Graded – module has assigned grade for student.
** If there are multiple grades for this activity, you can select which one is used to determine completion. (We will not implement this selection in the user interface for the first release. It will always use the first grade.)
** This condition is implemented by a hook in gradebook that runs at the point where a grade is set.
* Viewed – student has viewed module.
** For this to be supported, the module must call a function completion_set_module_viewed($cm) when it thinks that the user has ‘viewed’ the activity. It also needs to indicate that it supports it via ''module''_supports(FEATURE_COMPLETION_TRACKS_VIEWS).
==== Custom conditions ====
Modules can support arbitrary custom conditions (with their own form components to configure these, and their own data storage to track them).

Example conditions might be:
* Forum
** User has made N posts.
** User has made N replies.
** Other people have posted N replies to discussions created by this user. (''This an example of a more complex possibility, not necessarily something that would be a good idea.'')
* Wiki
** User has edited N different pages.
** User has edited pages N times.
* Choice
** User has voted.
It is up to the module to determine when a condition has been met and update the user’s completion.

As part of this project I plan to create some custom conditions for one or a few modules (probably just forum), and implement view tracking for a wider range of modules.
==== Combining conditions ====
If an activity has both the standard grade condition, and module conditions, these are currently combined via Boolean AND. Modules that support multiple conditions should usually also AND them as this will make life simpler for developer and users; however this is up to the module, as it creates its own form fields and data items.

In the future we may (or may not!) provide the ability to choose boolean OR instead. Some of the API functions contain a parameter that indicates how results should be combined. At present this is always set to AND.
=== Expected date ===
An activity can optionally have an expected completion date. This date currently has no effect and is not shown to students, but it appears to teachers when viewing progress. It's intended so that teachers can see when students are having problems and maybe offer assistance.

In future it might be possible to export this data – e.g. the list of students who are 'late' – to external systemss.
=== Database ===
(''Prefix is shown as _. Constants are defined for all values here.'')
* _course
** +Field enablecompletion, unsigned int (1) default 0 not null.1 = enable completion options for activities (if enabled at site level). This is the user-interface default that applies to new courses when completion is enabled for the site.0 = disable and hide options. This is the database default that will apply to existing courses.
* _course_modules
** +Field completion, unsigned int (1) default 0 not null.0 = No progress tracking for this activity.1 = Manual completion tracking.2 = Automatic completion tracking.
** +Field completiongradeitemnumber, unsigned int(10) default 0.NULL = Grade information not used for completion.0,1,… = Use first/second/N<sup>th</sup> grade item supplied by this activity.
** +Field completionview, unsigned int (1) default 0 not null.0 = View not required for completion.1 = View required for completion.
** +Field completionexpected, unsigned int (10) default 0 not null.0 = No particular date expected for completion<nowiki>* = time (seconds since epoch) by which activity is expected to be completed. </nowiki>
* New table _course_modules_completion which stores completion state for a user on each activity.
** id.
** coursemoduleid<nowiki> [index].</nowiki>
** userid<nowiki> [index]</nowiki>.
** completionstate, unsigned int(1) not null.(The absence of a row in the table counts the same as 0 here.)0 = not completed.1 = completed.2 = completed, passed.3 = completed, failed.
** viewed, unsigned int(1)null = not tracked0 = not viewed1 = viewedOnly stored if the activity is tracking viewed state.
** timemodified, unsigned int (10) not null.Last date the state changed, in seconds since epoch.
=== Capabilities ===
* moodle/course:viewprogress<nowiki> [default Teacher, Editing Teacher, Course Creator]</nowiki>Users with this permission can view progress of students on the course. If the course is set to visible groups mode, or the user also has accessallgroups, then they can see all groups. Otherwise they can only see groups they belong to.
=== Admin ===
A new admin setting progresstrackedroles stores a list of the roles that are considered relevant when displaying progress. (Other roles can still use the completion system, but won’t be shown on the progress screen.) This setting is editable via standard admin screens.
=== API ===
These functions will be included in a completionlib.php.
* completion_is_enabled($course=null,$cm=null)Returns true if completion is enabled. With no parameters, returns the site value; when course is specified, checks course as well.If course-module is specified, the return value is the same as the value of completion from course_modules.
* completion_update_state($course,$cm, $possibleresult=COMPLETION_UNKNOWN,$userid=0)Called to update completion state on the activity $cm for the given or current user. This obtains grade/viewable information if necessary and then asks the module whether the activity has been completed.It is called whenever a grade is updated on an activity that uses grades for completion and, by modules, whenever a module-specific piece of data that might affect completion has changed.
* $possibleresult is included for performance reasons to avoid recalculating completion when not necessary. Set to COMPLETION_COMPLETE or COMPLETION_NOTCOMPLETE, it indicates that the change which necessitated calling this function can only result in that type of state. For example, if there is a condition that the user must make 5 forum posts, we would call this function in response to any new post. But if the state is already ‘complete’, there is no point going through counting posts, checking grades, etc. This hint allows the code to skip further work if the user’s state is already the target. Once retrieved we will cache the state in session so that frequently, no database queries are required.
* For performance reasons, modules should still only call this function when necessary. The forum should not call this function whenever a new post is made, unless the completion option for counting posts is actually turned on for that forum.
* When a module is set to manual completion, this function is used to directly toggle completion. The completion value is set to $possibleresult.
* completion_set_module_viewed($course,$cm,$userid=0)Called when a module is viewed. If view-based completion is enabled (in $cm) then it sets the 'viewed' flag and calls update_completion_state.
* completion_count_user_data($cm)Called to determine whether any users have already completed an activity (if so, returns the number). This is used by the module settings form to determine whether completion settings should be 'locked'.
* completion_delete_all_state($course,$cm)Called at the point where course-module entries are deleted. Deletes all completion state data for that course-module.
* completion_reset_all_state($course,$cm)Deletes existing completion state for all users in this activity, then recalculates it by calling update_completion_state a lot for (i) all state-tracked users (those with progresstrackedroles roles in this activity’s context), (ii) all users who have stored completion state for this activity.Needs to be called if completion conditions change.
* completion_get_data($course,$cm,$wholecourse=false,$userid=0)Obtains completion data for a particular user related to a given activity. User defaults to current user.The $wholecourse parameter is a hint that, if it isn't already available, the system should retrieve into cache the completion data for all course activities now (so that future requests for other activities can be satisfied from cache).
* completion_get_activities($course)Gets course-module objects for all activities on a course that have completion turned on. (''Used by the progress report.'')
* completion_get_progress_all($course,$sortfirstname=false,$groupid=0)Obtains progress of all users in a course (or group) across all activities in that course for which completion tracking is enabled. (''Used by the progress report.'')
* completion_inform_grade_changed($course,$cm,&$item,&$grade,$deleted)Called to notify the completion system when a user's grade changes. Does nothing (quickly) if completion is not enabled for the item; if completion is enabled and depends on grade, calls completion_update_state. (''Provided only for use by the gradebook.'')
=== Module changes ===
There is no requirement for any module changes to support the completion system. Existing modules continue to work.

If no changes are made to a module, then manual completion (where the user ticks the box themselves) is supported for activities of that type, and automatic completion is not offered as an option in the activity settings screen.

Progressively more changes are required when implementing more detailed completion support for a module.
==== View support ====
To support the 'complete when viewed' feature, a module must do the following:
* Implement ''module''_supports() as follows:function ''module''<nowiki>_supports($feature) { switch($feature) { case FEATURE_COMPLETION_TRACKS_VIEWS: return true; default: return false; }}</nowiki>
* Add calls to completion_set_module_viewed whenever the module considers that it has been 'viewed'.
** It is up to the module to determine what this means. However most modules might put this call in view.php, near print_footer once it is clear that no errors occurred.
** This function does not take a significant time to run if view-based completion is not enabled, so you don't need to put the call inside an if.
==== Grade support ====
If a module provides grades, making ''module''_supports() return true for FEATURE_GRADE_HAS_GRADES will make these accessible to the completion system.
==== Custom completion ====
Supporting module-specific custom completion conditions requires extra work:
* Decide how to store the settings for these extra conditions (probably in your module's main table). Change your database tables to allow this.
* Add FEATURE_COMPLETION_HAS_RULES to your ''module''_supports().
* Add the extra controls to your mod_form.php.
** Override the method add_completion_rules() so that it adds extra form elements for your controls (the method is called at the right point so that they are added in the 'completion' box), and returns a list of the form elements (this is used to enable/disable them appropriately).
** Override the function completion_rule_enabled($data) so that it returns true if the supplied data means that at least one of the module's completion conditions is turned on. This is used to prevent the user from choosing 'automatic' completion if they don't also enable at least one condition.
** You may need to modify other functions such as definition_after_data() and get_data to set up your form controls appropriately based on the data from the database, or vice versa.
* In your lib.php, implement the new function ''module''_get_completion_state($course,$cm,$userid,$logic).
** If the specified module instance has completion requirements, this should return true (if they have been met) or false (if they haven't). The system will later combine this value with possible other completion requirements (view or grades).
** $logic is either COMPLETION_AND or COMPLETION_OR, indicating which type of Boolean logic should be used when there are multiple conditions.
** If completion conditions are not enabled for this particular instance, the function should return $logic (not false).
* In your module code, when something changes which might affect completion, call completion_update_state
=== Example of system operation ===
Assume that the forum offers an option to check completion based on the number of posts (complete when you’ve made N posts).

Every time a user makes a new post:
* Forum checks if completion tracking based on the number of posts is enabled (this would probably be an option in $forum). If not, it does nothing (''stop'').
* Forum calls completion_update_state($cm,COMPLETION_COMPLETE).
* System looks up the user’s current completion state for $cm. If the current state is already COMPLETION_COMPLETE (or COMPLETE_PASS or COMPLETE_FAIL) then it returns with no further action (''stop'').
* If grade-based completion is enabled, system obtains grade and checks it. If viewed-completion is enabled, system checks whether the module has been viewed.
* If the forum has its own completion rules, then the system calls forum_get_completion_state().
* The forum checks its own rules, including the number of posts and anything else that’s enabled. It returns true if these rules are met and false if they’re not.
* Combining this data, the system decides whether to update the completion state. If an update is needed, it makes the change in the database.
=== Activity UI (course page) ===
The user interface for students on the course view page needs to allow for displaying progress to students and, where completion is set to manual, allowing students to tick their own progress boxes.

I have based this suggested interface on experience here at the OU. The interface will be implemented via changes to print_section and course view.php.
* Completion displays alongside each activity for which completion is enabled, to the right of the section. (This conveniently separates it from the functional information at the left, and means that all the progress markers line up with each other.)
* Automatic completion displays as a tick or cross icon, by default coloured green and red (accessible colours will be chosen), or some kind of faint outline if something isn’t completed yet. The cross icon is used if completion state is 1.
* Manual completion displays using two more icons (‘manual tick’ and ‘manual blank’). Possible icons would be the same tick with a heavy dotted box around it, and an empty dotted box. The title of the icon is an interface clue to the user e.g. ‘Click to mark this activity completed’.When AJAX is not enabled, the manual icons link to a URL that toggles the completion value then redirects straight back to the course page.When AJAX is enabled, the manual icons use YUI to adjust the completion value without reloading the page. In this case some kind of animation – for example, the word ‘Saved’ appearing next to the icon for a second before fading away – will be used to indicate to users that their change has taken effect.
* If completion is not enabled for an activity (or for the course, site, etc) then the print_section display is the same as at present.
* When editing is turned on, completion information always displays as ticked regardless of the user’s actual completion setting. This makes it easy to see that completion is enabled for that activity.
I will get a graphic designer to look at the icons to use. To reiterate, there are six icons:
* automatic completion, not completed yet (above, not actually shown on its own, but would be a faint grey dotted box)
* automatic completion, completed (above, slightly grey tick, with faint grey dotted surround)
* automatic completion, pass (not shown, e.g. could be a green tick)
* automatic completion, fail (not shown, e.g. could be a red cross)
* manual completion, not completed (heavy black dotted outline)
* manual completion, completed (heavy black dotted outline with black tick)
It may need some work to make the manual ones look clickable and the automatic ones look not clickable, but not irrelevant either. For example we might have to resort to crappy 3D button-style shading on the manual ones. This is what I've done (badly) in the initial version of the icons which I have made.
=== Configuration UI (activity settings page) ===
Each activity’s completion settings can be configured on the standard activity settings page. These settings only appear if completion is enabled for the course and site.

The interface will be implemented via a change to the standard_coursemodule_elements function and a new optional form member function completion_add_rules(), as mentioned above, which is called (from within standard_coursemodule_elements) to add the activity-specific form elements.

We also need to determine whether the activity supports grades. This will be determined via the new ''module_''supports() function. (Note that there are existing functions for finding out whether a module ''instance'' has a grade, but not for finding out whether a module supports grades if it hasn't been created yet.)

((TODO: Diagram needs redoing))
* A dropdown allows choice of the three completion options – none, manual, automatic. (All three are shown in the diagrams below.) If the module does not support its own completion conditions, and does not support grades, then the ‘automatic’ option will not appear.
* A ‘view’ checkbox only appears if the module supports view tracking. If completion is not set to automatic, it will be greyed out. It allows you to mark something complete as soon as the user goes there once.
* A 'require grade' checkbox only appears if the module supports grades. If completion is not set to automatic, it will be greyed out.
** At this point we could have a dropdown selector to choose which grade item to use if there is more than one. However, at least for the first release, I am not providing a user interface for that feature.
* Module-specific settings, if any, are included. These are also greyed out if completion is not set to automatic. The module can add any number of settings. It is responsible for storing the data from these as part of its normal form processing.
* <nowiki>An expected completion date (default disabled) is given. This can be enabled for manual or automatic completion. It has no practical effect but displays on the progress screen. The intention is that those who design a course can set these dates at key points in the course. During the course, teachers can look at the progress report and use the dates as a guideline to check whether students are falling behind. [At a later date it might be possible to do other things with this data, such as export a list of 'late' students to an external system.]</nowiki>
* If anybody already has stored completion state for this activity, completion settings will be locked: they appear, but read-only. A button allows you to unlock the settings (making those fields editable again); after you do that and save the form, existing completion data is wiped and recalculated against the new conditions. A warning by the button explains that changing completion conditions after students complete things is not a good idea.
=== Progress tracking UI ===
Teachers wishing to track student progress can do so via the admin block. The existing course reports page will include a link to view student progress if the user has viewprogress capability.

The resulting page shows a summary of progress either for a particular group, or for all students in the course, according to the normal rules for group selection. It may include a standard group dropdown too.
# Progress is shown in a table. Students (everyone with a role in progresstrackedroles<nowiki>) are displayed down the left of the table and for activities that have completion enabled, the activity names [with expected completion dates, if set] are displayed across the top. Students can be sorted by first name or last name. The student names link to profiles and activity names link to the activities.</nowiki>
# The cells in this grid show progress indicators using the same icons as used on the course view page, although these icons are not clickable in the report. For each cell, the title, which you can see by hovering over it, indicates the state of the cell and the time modified (‘Completed 12/9/08 13:47’) as well as the student's name and the activity name (in case you are scrolling around a table that doesn't fit on-screen).
# A link at the bottom allows this table to be downloaded in CSV format. The downloaded version contains the same data, using two columns (‘state’ and ‘date’) for each activity.
=== Performance ===
==== Course view ====
When completion is enabled for a course, the course view page needs to obtain completion information. This will be cached in session and retrieved efficiently (hopefully 1 query) the first time.
==== Module pages ====
There is no performance impact when using modules that do not support completion, or where completion is disabled.

When you take an action that potentially involves completion (e.g. if you make a forum post to a forum that has enabled automatic completion when you reach N posts) the same completion state cache is used to read the current state of the data, so this should need no queries (you probably already saw the front page).

If your action could potentially change that completion state (e.g. you have not already completed the activity and you just made an additional forum post) there will be an additional cost at that time, depending on the activity – in this case, the forum will do a query to find out how many posts you've made. Because these actions occur relatively rarely, this should not cause a serious problem. (Once you have completed the activity, making another post will not incur the performance penalty.)

View-related completion tracking, the part most potentially problematic, will behave similarly: the first time you view something that has a 'viewed' requirement, it will make extra queries as it marks it viewed (or, if you viewed it in a previous session, loads up that information). After that the information will be cached in your session.
=== Backup and restore ===
* When users are included in backup, course backup will include the contents of the _course_modules_completion table.
* Course and course-modules backup will be modified to include the new fields in those tables.
== Conditional availability ==
=== Conditional options ===
There is no specific option to enable this part of the feature (?). The parts which depend on the completion system are enabled using the completion flag.
=== Available conditions ===
You can place conditions on any activity. Conditions are always combined with Boolean AND, i.e. all conditions must be met before the activity becomes available. Unlike completion, conditions are not module-dependent. There are two types of condition:
# Conditional on date. You can have both of these conditions if required.
#* On or after date – activity becomes available on given date.
#* Before date – activity becomes unavailable on given date.
# Conditional on other activities. You can have as many of these conditions as desired.
#* Activity must be completed – any kind of completion will do.
#* Activity must be completed and passed – completion must have been graded and displayed with a pass mark (tick icon).
#* Activity must be graded at least/at most ''N''.
=== Database ===
* _course_modules
** New field availablefrom, unsigned int (10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch</nowiki>) after which activity becomes available.
** New field availableuntil, unsigned int(10) not null default 0.0 = Not conditional on date.<nowiki>* = Time (seconds since epoch) after which activity becomes unavailable.</nowiki>
** New field showavailability, unsigned int (1) not null default 0.0 = Activity does not appear at all if conditions are not met.1 = If conditions are not met, activity appears but greyed out (‘hidden’ style) with no link and a short explanation of when it will be available.
* New table _course_modules_avail(able?) which stores any per-module conditions.
** id.
** coursemoduleid<nowiki> [index]</nowiki>.ID of the module that is being restricted.
** cmsourceid.ID of module that the restriction is based on.
** requiredcompletion, unsigned int(1) not null default 0.0 = no required completion.1 = required completed.2 = required completed and passed.3 = required completed and failed.
** gradesign, varchar(2).NULL = no required grade.<nowiki>‘<’, ‘<=</nowiki>’, ‘>’, ‘>=’ = requirement for grade.
** requiredgrade, number(10,5 decimals).Grade boundary used together with the above sign. May be null.
=== API ===
Two new functions:
* availability_is_available($cm)Returns true if the module is available to students (it is visible, plus availability conditions, if any, are met). Does not include course access conditions, which it assumes have already been checked.This is a slot-in replacement where code checks for $cm->visible at key points such as in require_login.
* availability_get_display_details($cm)Obtains information about the activity’s availability which is required in order to display (or not display) a link to the activity. Returns an object with the following fields:->available – If true, activity is available; users should be allowed to access it / get links to it.->show – If true, activity should be displayed (even to users who do not have viewhiddenactivities)->info – Informational string. Blank if the activity is available.
Other changes:
* For performance reasons we need to cache the conditions in _course_modules_available. Best option is to use existing get_fast_modinfo infrastructure. This should not be hard. The above two functions will use this cache.
=== Configuration UI (activity settings page) ===
The configuration UI will be implemented as part of standard_coursemodule_elements in the module forms. The existing ‘visible to students’ option (not changed in database/code) is moved within this UI.

This UI will appear even if completion is not enabled, but the parts related to completion will not show. So if completion is not enabled you will still be able to set available dates if you like, and the interface will remain consistent. The diagram below shows, first, the version that appears with completion not enabled, and then the one you get with completion enabled.

((There should be a diagram here, not sure it will show in the wiki version))

[[Image:]]
* The actual ‘available from’ options should include time as well as date. ‘Available from’ should default to midnight tomorrow; ‘Available until’ should default to 23:59 today. (I got bored laying out combo boxes.)
* ‘Information display’ controls whether informational text is displayed to students when an activity is not available. (See below.) The default is not to show information.
* The list of other activities which might have conditions includes only those other activities on the course which either have completion information, or a grade. Anything which doesn’t have completion information or a grade is omitted.
* Only one condition is permitted per other activity. This isn’t a restriction of the back-end, it just makes the UI simpler.
* The condition type dropdown by each activity is adjusted dynamically to include only options that are valid for that activity:
** ‘Completed’ appears only if completion is enabled for the activity.
** ‘Completed with pass’ and ‘Completed with fail’ (which I missed off the diagram by accident) appear only if completion is enabled for the activity, and set to a grade item, and the grade item contains a pass mark.
** The grade conditions appear only if the activity has a grade item.
* The grade box is a text-entry field. Users type in the floating-point number version of the required grade.
=== Activity UI (course page) ===
(This will be accomplished via code changes to print_section. Logic is basically the same as for the current visible flag.)

For available activities, the display obviously does not change. Unavailable activities will be displayed as follows:
* If the current user has viewhiddenactivities:
** The activity displays using the CSS style for hidden activities.
** The informational message as to why the activity isn’t available is displayed (even if showinfo is not set).
* If the current user does not have viewhiddenactivities:
** If showavailability is not set, or if the activity is actually hidden (visibility 0), the activity does not display at all.
** If showavailability is set and the activity isn’t hidden but is unavailable for some other reason, the name of the activity displays using the CSS style for hidden activities, but does not include an actual link to the activity. The informational message as to why the activity isn’t available is displayed.
Here are some examples of hidden activities with informational text:Assignment resources Available from 6 Oct 2008Assignment resources Available when Unit 1 Test grade is > 90Assignment resources Available when Tutor group forum is marked complete (+ other requirements)When there are multiple conditions, only one is shown. Date is considered first; the order after that is arbitrary.

Behaviour is the same when editing is turned on except that the ‘availability’ string moves to the line below so as not to clash with all those icons.
=== Performance ===
This adds a single quick database query to the course view page for courses which have enabled conditional activities / completion.

All other information is cached in modinfo<nowiki>, so does not have a performance penalty, save one problematic issue: the feature that allows arbitrary grade information to be considered. If you use pass/fail information, that’s fine, it’s there already in the completion data. But if you use a specific grade [and for example it could be different values for different activities] then the actual grade for the item needs to be retrieved on course view.</nowiki>

I don’t believe this will pose a massive performance issue as it only applies when modules are used as source for this kind of information. We should review this once it’s developed and, if necessary, optimise performance then. There are various caching approaches we could use.
=== Module delete ===
If you try to delete a module, it will check to see if that module is referenced by any other module as a condition. If that’s the case, you will not be allowed to delete it. An error message will include a link to the module edit page for the other module (so you can go there and delete the condition if you like).
=== Backup and restore ===
* The new _course_modules_available table will be backed up and restored.
** Partial restore needs to be handled. If your backup includes module A but not module B, and module A had a condition on B, then that condition will not be restored.
* Backup will also be modified to include the fields added to _course_modules.
* If you restore a course with a startdateoffset, it will offset the dates from the new _course_modules date fields.
== Module supported features ==
As part of the completion system, I needed a way for modules to indicate support of certain features, so I propose a generic one which I have implemented:
* A module API function ''module''_supports($feature) which returns false if the feature is not available, and true (or an object with more information, if needed for specific features) if it is.
* A standard API function module_supports($modulename,$feature) which works as follows:
** If the $modulename_supports_feature function exists, it calls that function and returns the result.
** Otherwise it returns false – or, if features are added that correspond to ‘legacy’ ones that we can find out another way (e.g. by looking to see if a function exists) then this can be done.
* A set of FEATURE_''xx'' constants. For this code, the following are necessary:
** FEATURE_GRADE_HAS_GRADE
** FEATURE_COMPLETION_TRACKS_VIEWS
** FEATURE_COMPLETION_HAS_RULES
* Other feature constants could be added as desired, e.g. FEATURE_CRON, etc. My initial implementation will include only the 'new' ones needed for this work.
Note that this implementation would not be appropriate if modules were changed to be fully object-oriented. However I don't expect that to happen in Moodle 2 so this is probably OK.
==See also==
* [[Conditional activities_Adding module support]]
* [[Conditional activities]]
[[Category:Conditional activities]]
[[Category:Completion]]

Survey 2 module

2015-11-20T12:27:39Z

Kordan:

{{Infobox Project
|name = New Survey module
|state = Development in progress
|tracker = MDL-36350
|discussion = https://moodle.org/mod/forum/discuss.php?d=215159
|assignee = MediaTouch 2000 srl - Daniele Cordella
}}

'''I am going to add make unstable surveypro since next monday with further developments.'''
'''Because of this, anybody wanting to upgrade the surveypro module up to current stable status should be use MOODLE_30_STABLE branch, no matter the Moodle version used (from 2.6.x to 3.0.x).

'''Since Monday November 23, 2015, master will be for development, and only will work under Moodle 3.0.0 and newer. MOODLE_30_STABLE will be the stable supported branch were fixes will be applied.'''

{{Moodle 2.6}}This page is for collecting feature requests for a the new Survey module that replaces Survey, Questionnaire and Feedback.

The module is currently under development, so the general features list will also include a completion status, if any. For those who like to test a prototype of the module a Github repo is available [https://docs.moodle.org/dev/Survey_2_module#Current_module_status].

==General features of the Module==
* translate previously built survey1, feedback and questionnaire at installation time. (The general idea for the module is currently translate at installation time all previous existing survey module instances. Questionnaire and feedback instances can be translated at will using an upgrade helper)
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* (available) save instances of survey2 as a template to reuse it or export it
* (available) import saved survey2 templates
* (partially available) support for groups and groupings
* (available custom css) custom user survey2 page layout (custom html and css, as it already is in database module)
* (available) download of submissions in txt, xls and ods
* (available) conditional branching
* (available) handle more than one input form template (and find a way to allow this or that layout to this or that user).
* (available) order survey fields in editing mode
* (available) group fields in the page layout with fieldset
* (available) relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* (available) email submissions to students/teachers/both/none
* email submissions to address specified in a designated question field (for surveys not requiring login)
* indication that students are currently taking (but haven't completed) the questionnaire
* (available) for text fields, simple data checking ('must be numeric', 'must contain X character', 'must have exact length n', etc.)
* (available) full web accessibility features to the same level as elsewhere in Moodle e.g. labels on text fields, fieldsets on groups of radio buttons & checkboxes.
* gradebook integration (to allow simple polls to control conditional activities)
** assigning grades to specific answers to specific questions in a survey
** may only work for certain question types (e.g. radio buttons, rating)
** once a student has a grade for their survey completion, that grade can be used elsewhere in the system to control activity display. usecase - simple poll with 1 question "what are you planning to study next", 5 radio buttons, each answer a different course assigned grade 20%, 40%, 60%, 80%, 100%. Then 5 conditional activities set up, for if grade <21%, <41% etc and each one has content specific to the course chosen in the radio button providing basic info on that subject. Or similarly if you have different focus areas in your course that students can self-select into/swap between a more complex survey could be used with this to decide which focus area to put students into.
* improve templates (to allow impact views and impressions)
* enhance the editing
* ability to have public surveys that do not require users to be logged in
* would be great for learners to be able to export using Portfolio Export. This would enable things such as self-assessments in Mahara.

==Instance settings page==
In the moudle instance settings page, the following fine grained control over the record submitted will be an optional Admin setting, so standard users with standard access to recor submitted can just work as usual.
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
* option whether to show results immediately after submission, or a thank you message with link to results.

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking
* conditional drop-down where the first list populates the second
* tabular question with multiple answers, of any depth.
: Occurrence Quantity Location
Bluebird 2 Hobart
Jay 1 Kingston
.
.
.

==Result display==

* report per survey, per user and per question
* report about non-respondent users
* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart

Would be great to be able to analyse the results according to a particular answer. eg: Show results for just one gender

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use [maybe later]
* question sets can be used across multiple courses [maybe later]
* questions can be re-ordered within an activity
* question sets can be combined to create a template
* questions can be deleted from an activity, but there should be an "are you sure" check first.

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

==Current module status==
The module currently under development is named Collection, so it can be easily deployed over existing installations with almost no impact on current Surveys. For those interested in testing, Daniele Cordella, the main developer of the module, prepared a Github repo from where you can download the module prototype in it's current status: https://github.com/kordan/moodle-mod_survey. Please note the module is aimed towards the development branch (master), using it on stable versions such as 2.2 or 2.3 is not supported. Note: prior to install the module, please 1) uninstall standard Moodle Survey module and remove the code from the mod/survey folder 2) replace mod/survey with the code form Github repository 3) visit Admin notification page or launch CLI update script.

==Future plans==
* community sharing and code refinements
* add module to contrib plugin as "Survey" to allow extensive testing as well as AMOS translations
* complete Questionanire and Feedback migration helpers
* integrate module into core for 2.5 release

Survey 2

2015-11-20T12:25:55Z

Kordan:

This is the starting point for finding out about (and joining in with) the project to replace the Survey, Feedback and Questionnaire modules with a new module called simply: Survey.

'''I am going to add make unstable surveypro since next monday with further developments.'''
'''Because of this, anybody wanting to upgrade the surveypro module up to current stable status should be use MOODLE_30_STABLE branch, no matter the Moodle version used (from 2.6.x to 3.0.x).

'''Since Monday November 23, 2015, master will be for development, and only will work under Moodle 3.0.0 and newer. MOODLE_30_STABLE will be the stable supported branch were fixes will be applied.'''

==Development process==

# Gather requirements from tracker, forums, users ([[Survey_2_brainstorm]])
# Vote for features and rank them
# Develop a detailed spec for the first version
# Develop basic framework for the module
# Review regularly
# Develop final module
# Integrate into core Moodle

Acceptance testing

2014-08-26T11:27:21Z

Kordan: /* Verify your installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I set the following fields to these values:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "User Blog"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behavior driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Verify your installation ==
* Test your installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/WAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvars" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.
For example, for MAMP you probably need to add:

<code php>
# Adding MAMP binaries communicate where CLI is
PATH="/Applications/MAMP/bin/php/php5.x.y/bin:$PATH"; export PATH
</code>

at the end of MAMP/Library/bin/envvars.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== Browser specific fixes ==

When running acceptance tests in conjunction with Selenium against Chrome, IE, or Safari there is a fix for the navigation bar that gets applied in order to avoid errors arising from a bug in the webdrivers for those browsers.

<b>The issue</b>: When an acceptance test goes to interact with an element on the page it first ensures that the element in the view-port and if not scrolls the browser to get the element into the view-port. If you are running against Chrome, IE, or Safari the browser scrolls the element only just inside the view-port. It doesn't however allow for any fixed position elements such as the navigation bar.
What happens: In some situations these browsers scroll up to reach a button, however not enough as the button ends up behind the navigation bar and cannot be interacted with.

<b>Our solution</b>: We can not change browser driver behaviour so we have integrated a work around. When running acceptance tests against one of these browsers we change the position attribute of the navigation bar from fixed to absolute. This is not ideal as it is not how the user experiences the site, however it allows us to run the full acceptance test suite against these browsers so we allowed it. A notice will be displayed when you start an acceptance test run if the browser specific fixes have been applied.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T12:17:53Z

Kordan: /* Verify your installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Verify your installation ==
* Test your installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/WAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.
In MAMP you probably need to add:

<code php>
# Adding MAMP binaries communicate where CLI is
PATH="/Applications/MAMP/bin/php/php5.x.y/bin:$PATH"; export PATH
</code>

at the end of MAMP/library/bin/envvars.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T12:15:32Z

Kordan: /* Verify your installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Verify your installation ==
* Test your installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/WAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.
In MAMP you probably need to add:

<code php>
# Adding MAMP binaries communicate where CLI is
PATH="/Applications/MAMP/bin/php/php5.5.3/bin:$PATH"; export PATH
</code>

at the end of MAMP/library/bin/envvars.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T11:49:56Z

Kordan: /* Verify your installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Verify your installation ==
* Test your installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.
In MAMP you probably need to add:

<code php>
# Adding MAMP binaries communicate where CLI is
PATH="/Applications/MAMP/bin/php/php5.5.3/bin:$PATH"; export PATH
</code>

at the end of MAMP/library/bin/envvars.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T11:49:05Z

Kordan: /* Verify your installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Verify your installation ==
* Test your installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.
In MAMP you probably need to add:

<code php>
# Adding MAMP binaries communicate where CLI is
PATH="/Applications/MAMP/bin/php/php5.5.3/bin:$PATH"; export PATH
</code>

at the end of MAMP/library/bin/envvar.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T11:43:37Z

Kordan: /* Installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Verify your installation ==
* Test your installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T11:42:52Z

Kordan: /* Installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Installation ==
* Test the right installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Acceptance testing

2014-04-18T11:42:04Z

Kordan: /* Installation */

== Introduction ==
This page describes how we describe Moodle's functionalities and automatically test them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.

For technical info: [[Behat integration]]

=== How it works ===
Behat parses and executes features files which describe Moodle's features (for example ''Post in a forum''). Each feature file is composed of many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed of steps (for example ''I press "Post to forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into a PHP method and is executed.

These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.

=== Examples ===

Note that these snippets are only examples and may not work.

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_wwwroot = 'http://127.0.0.1'; // must be different from wwwroot
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
** Use $CFG->behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG->wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use "http://localhost:8000" or the value you set when you started it.
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"
* Test the right installation by browsing your /admin/tool/behat/index.php page.
If you are using MAMP/XAMPP and don't get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the "envvar" file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.

== Running tests ==
# (Optional) Start the PHP built-in web server if you configured the $CFG->behat_wwwroot to use it:
#* 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)
# (Optional) 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'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
#* 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, try downloading the latest Selenium release from it's website as explained above
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (if you want to prevent access to test environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

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

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

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.

== Run behat using different browsers ==

Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL'''. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Save screenshots of failures'''. You can use $CFG->behat_screenshots_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.

<code language="php">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>

:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''' option was removed in 2.7, it is recommended to always set $CFG->behat_wwwroot even in older versions instead.
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
* '''Extra allowed settings''', moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG->behat_extraallowedsettings (see config-dist.php for examples).
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Contributing ==

You can contribute the effort to automatically test all of Moodle's functionalities, please follow the [[contributor guide|https://docs.moodle.org/dev/Acceptance_testing/Contributing_automated_tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: https://docs.moodle.org/dev/Acceptance_testing/Contributing_to_Moodle_behat_extension.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="yaml">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work.
## The prefixes ''Given'', ''When'' and ''Then'' separates the scenario in 3 parts, the initial context setup (''Given''), the action that provokes a change in the system (''When'') and the validation of that change outcomes (''Then'') So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -> And -> And -> When -> And -> And -> Then -> And -> And -> And. Once we begin with the first ''Then'' we can consider that we are checking the outcomes so all the steps from there should be prefixed with ''Then''
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="yaml">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="yaml">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* You can use '''Scenario outlines''' if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example.
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

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

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

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exist:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exist:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*
** The required fields are activity, course and idnumber
** Uses activity to specify the activity type
** Uses the course shortname as course reference
** Other activity-dependant fields can be specified by it's field name
Given the following "activities" exist:
| activity | course | idnumber | name | intro |
| assign | C1 | assign1 | Test assignment name | Test assignment description |
| data | C1 | data1 | Test database name | Test database description |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exist:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exist:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exist:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exist:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* Roles
** The required field is shortname
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage
Given the following "roles" exist:
| shortname | name | description | archetype |
| custom1 | Custom Role 1 | | editingteacher |

* Role assigns
** The required fields are user, role, contextlevel and reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "role assigns" exist:
| user | role | contextlevel | reference |
| user1 | manager | System | |
| user2 | editingteacher | Category | CATEGORY1 |
| user3 | editingteacher | Course | COURSE1 |

* System role assigns (deprecated in favour of role assigns, see item right above this one)
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exist:
| user | role |
| testuser | manager |

* Permission overrides
** The required fields are capability, permissions, role, and the contextlevel + it's reference
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.
Given the following "permission overrides" exist:
| capability | permission | role | contextlevel | reference |
| mod/forum:editanypost | Allow | student | Course | C1 |
| mod/forum:replynews | Prevent | editingteacher | Course | C1 |
| mod/paquiro:sings | Prohibit | student | System | |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exist:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exist:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exist:
| name | idnumber |
| Cohort 1 | COHORT1 |

==== Referencing contexts ====

Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:
* contextlevel: '''System''', '''User''', '''Category''', '''Course''' and '''Activity Module'''
* reference:
** System: Nothing, just leave the the cell empty
** User: The user '''username'''
** Category: The category '''idnumber'''
** Course: The course '''shortname'''
** Activity module: The activity '''idnumber'''

The data generators which makes use of these format are pointing to here.

=== Features check list ===
* It's a new feature or a new scenario of an existing feature
* Is using the '''Background''' section or '''Scenario Outlines''' instead of duplicating steps (only when applicable)
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features
* Covers both JS and non-JS environments

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don't use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle's user interface to reach the setting page and change it's value.

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* This second comment line will be not shown in the steps definitions list as it is only
* reading the first line in the comment block.
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "' . get_string('login') . '"'),
new Given('I fill in "' . get_string('username') . '" with "' . $this->escape($username) . '"'),
new Given('I fill in "' . get_string('password') . '" with "'. $this->escape($username) . '"'),
new Given('I press "' . get_string('login') . '"')
);
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this->running_javascript() to deal with both
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

== Troubleshooting ==

=== How can you tell if Selenium is running? ===

Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.

=== How can I stop Selenium? ===

Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs "OKOK".

=== Behat tells me that lots of steps are undefined ===

You probably forgot the --config option in the behat command.

== See also ==

* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]
* Technical info: [[Behat integration]]
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors
[[Category:Behat]][[Category:Quality Assurance]]

[[es:Prueba de aceptación]]

Migrating logging calls in plugins

2014-03-08T19:57:54Z

Kordan: /* Step 2. Create event class */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['eventEVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_logdata() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

== "Installation" of events ==

Please never forget that you have to bump the plugin version in order to get all the new events "installed"

Migrating logging calls in plugins

2014-03-06T09:25:23Z

Kordan: /* Validation and testing */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['eventEVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_log_data() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

== "Installation" of events ==

Please never forget that you have to bump the plugin version in order to get all the new events "installed"

Migrating logging calls in plugins

2014-03-06T09:23:40Z

Kordan: /* Validation and testing */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['eventEVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_log_data() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

Please never forget that you have to bump the plugin version in order to get all the new events "installed"

Migrating logging calls in plugins

2014-03-04T12:11:49Z

Kordan: /* Step 2. Create event class */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['eventEVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_log_data() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

Migrating logging calls in plugins

2014-03-04T12:11:28Z

Kordan: /* Step 1. Choose a name for the event */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['eventEVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('event_EVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_log_data() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

Migrating logging calls in plugins

2014-03-04T10:28:45Z

Kordan: /* Step 2. Create event class */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['event_EVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('event_EVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_log_data() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

Migrating logging calls in plugins

2014-03-04T09:27:28Z

Kordan: /* Step 1. Choose a name for the event */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about events names.

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<pre style="background: #DFF">
$string['event_EVENTNAME] = 'Something has happened';
</pre>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "User {$this->userid} has ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_log_data() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</pre>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<pre>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</pre>

...becomes...

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</pre>

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</pre>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord); // You can use $PAGE->activityrecord if you have set it or skip this line if you don't have a record.
$event->trigger();
</pre>

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<pre style="background: #FFA">
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</pre>

=== Step 3. Triggering the event ===

<pre style="background: #FDD">
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</pre>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/master/lib/classes/event/course_module_deleted.php#L69
* Triggering: https://github.com/moodle/moodle/blob/master/course/lib.php#L1716..L1727
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect record snapshot identified by 'objecttable' and 'objectid' but developer may also add snapshot of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be actually fetched at any time between the triggering of event and its observation.

=== can_view() ===

The future of this function is not yet decided. It was intended as a callback allowing each event to determine whether the current user can see the logged event. But in reality checking various capabilities on a large number of records is a very expensive process. At the moment '''events do not override this function and it is not used'''. If you are interested in this method's future, watch/vote/comment on MDL-44107.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

File:recurrence.png

2013-06-25T06:02:44Z

Kordan:

Survey element types

2013-06-25T06:02:13Z

Kordan: /* Questions */

Elements building a survey are divided in two types: "question" or "format".

The semantics which distinguishes between "question" or "format" is this: a "question" is the form element providing what remote user submitted, "format" is ONLY a form aesthetic element.

Questions such as formats differ each other by plugin.

There are some question plugin provided with survey such as some format plugin too.

So hierarchically a survey is done by:
*Survey form
** elements
*** element type questions (shortly called "questions")
**** question plugin 1
**** question plugin 2
**** question plugin ...
*** element type formats (shortly called "formats")
**** format plugin 1
**** format plugin 2
**** format plugin ...
==Questions==

(Click any screenshot below to see it enlarged.)
{|
|[[File:age.png|thumb|"Age" question type]]
|[[File:autofill.png|thumb|"Autofill" question type]]
|[[File:boolean.png|thumb|"Boolean" question type]]
|-
|[[File:checkbox.png|thumb|"Check box" question type]]
|[[File:date.png|thumb|"Date" question type]]
|[[File:datetime.png|thumb|"Date and time" question type]]
|-
|[[File:fileupload.png|thumb|"Attachment" question type]]
|[[File:integer.png|thumb|"Integer" question type]]
|[[File:multiselect.png|thumb|"Multi select" question type]]
|-
|[[File:numeric.png|thumb|"Numeric" question type]]
|[[File:radiobutton.png|thumb|"Radio button" question type]]
|[[File:rate.png|thumb|"Rate" question type]]
|-
|[[File:recurrence.png|thumb|"Recurrence" question type]]
|[[File:select.png|thumb|"Select" question type]]
|[[File:shortdate.png|thumb|"Short date" question type]]
|-
|[[File:shorttext.png|thumb|"Short text" question type]]
|[[File:textarea.png|thumb|"text area" question type]]
|[[File:time.png|thumb|"time" question type]]
|}

==Formats==

{|
|[[File:fieldset.png|thumb|"Fieldset" format type]]
|[[File:label.png|thumb|"Label" format type]]
|[[File:pagebreak.png|thumb|"Page break" format type]]
|}

Survey element types

2013-06-25T06:00:52Z

Kordan:

Elements building a survey are divided in two types: "question" or "format".

The semantics which distinguishes between "question" or "format" is this: a "question" is the form element providing what remote user submitted, "format" is ONLY a form aesthetic element.

Questions such as formats differ each other by plugin.

There are some question plugin provided with survey such as some format plugin too.

So hierarchically a survey is done by:
*Survey form
** elements
*** element type questions (shortly called "questions")
**** question plugin 1
**** question plugin 2
**** question plugin ...
*** element type formats (shortly called "formats")
**** format plugin 1
**** format plugin 2
**** format plugin ...
==Questions==

(Click any screenshot below to see it enlarged.)
{|
|[[File:age.png|thumb|"Age" question type]]
|[[File:autofill.png|thumb|"Autofill" question type]]
|[[File:boolean.png|thumb|"Boolean" question type]]
|-
|[[File:checkbox.png|thumb|"Check box" question type]]
|[[File:date.png|thumb|"Date" question type]]
|[[File:datetime.png|thumb|"Date and time" question type]]
|-
|[[File:fileupload.png|thumb|"Attachment" question type]]
|[[File:integer.png|thumb|"Integer" question type]]
|[[File:multiselect.png|thumb|"Multi select" question type]]
|-
|[[File:numeric.png|thumb|"Numeric" question type]]
|[[File:radiobutton.png|thumb|"Radio button" question type]]
|[[File:rate.png|thumb|"Rate" question type]]
|-
|[[File:select.png|thumb|"Select" question type]]
|[[File:shortdate.png|thumb|"Short date" question type]]
|[[File:shorttext.png|thumb|"Short text" question type]]
|-
|[[File:textarea.png|thumb|"text area" question type]]
|[[File:time.png|thumb|"time" question type]]
|}

==Formats==

{|
|[[File:fieldset.png|thumb|"Fieldset" format type]]
|[[File:label.png|thumb|"Label" format type]]
|[[File:pagebreak.png|thumb|"Page break" format type]]
|}

Rationale

2013-05-23T10:24:05Z

Kordan: /* at report level */

The idea standing after the development of this module is to provide answers to the more frequent requirements of end users.

Their frequent requirements are:
==at element level==
* possibility to add custom question type matching specific needs
* question predefined value
* question level validation
* reduce, as much as possible, the range of possible answers
* mandatory questions
* have some typographic option to display elements in different ways
* tools to quickly reuse set a specific questions that never change in each survey
==at survey level==
* conditional branching
* force the user to provide a his/her own answer
* subset of questions available to teachers ONLY
* include permission management for groups of users submitting surveys in behalf of the same institution
* use captcha
* allow/deny submitted survey modification (including deletion)
* allow a backup copy of submitted surveys each time they are modified in order to preserve their history
* speed up form fill as much as it is possible

==at report level==
* possibility to add custom reports
* export of submitted surveys

Rationale

2013-05-23T10:22:52Z

Kordan: /* at survey level */

Rationale

2013-05-23T10:20:10Z

Kordan: /* at survey level */

The idea standing after the development of this module is to provide answers to the more frequent requirements of end users.

Their frequent requirements are:
==at element level==
* possibility to add custom question type matching specific needs
* question predefined value
* question level validation
* reduce, as much as possible, the range of possible answers
* mandatory questions
* have some typographic option to display elements in different ways
* tools to quickly reuse set a specific questions that never change in each survey
==at survey level==
* conditional branching
* force the user to provide a his/her own answer
* subset of questions available to teachers ONLY
* include permission management for groups of users submitting surveys in behalf of the same institution
* use captcha
* allow/deny submitted survey modification (including deletion)
* save a backup copy of each submitted survey each time it is modified in order to have the History of the record
* speed up form fill as much as it is possible

==at report level==
* custom reports
* export of submitted surveys

Rationale

2013-05-23T10:18:46Z

Kordan: /* at survey level */

The idea standing after the development of this module is to provide answers to the more frequent requirements of end users.

Their frequent requirements are:
==at element level==
* possibility to add custom question type matching specific needs
* question predefined value
* question level validation
* reduce, as much as possible, the range of possible answers
* mandatory questions
* have some typographic option to display elements in different ways
* tools to quickly reuse set a specific questions that never change in each survey
==at survey level==
* conditional branching
* force the user to provide a his/her own answer
* subset of questions available to teachers ONLY
* a way to allow a set of users to submit the same survey writing it at different times
* use captcha
* allow/deny submitted survey modification (including deletion)
* save a backup copy of each submitted survey each time it is modified in order to have the History of the record
* speed up form fill as much as it is possible

==at report level==
* custom reports
* export of submitted surveys

File:shortdate.png

2013-05-23T10:09:03Z

Kordan: uploaded a new version of "File:shortdate.png"

File:datetime.png

2013-05-23T10:08:25Z

Kordan: uploaded a new version of "File:datetime.png"

File:time.png

2013-05-23T10:06:50Z

Kordan: uploaded a new version of "File:time.png"

File:textarea.png

2013-05-23T10:04:21Z

Kordan: uploaded a new version of "File:textarea.png"

File:shorttext.png

2013-05-23T10:04:10Z

Kordan: uploaded a new version of "File:shorttext.png"

File:datetime.png

2013-05-23T10:03:42Z

Kordan: uploaded a new version of "File:datetime.png"

File:select.png

2013-05-23T10:03:38Z

Kordan: uploaded a new version of "File:select.png"

File:rate.png

2013-05-23T10:03:13Z

Kordan: uploaded a new version of "File:rate.png"

File:radiobutton.png

2013-05-23T10:02:51Z

Kordan: uploaded a new version of "File:radiobutton.png"

File:numeric.png

2013-05-23T10:02:24Z

Kordan: uploaded a new version of "File:numeric.png"

File:multiselect.png

2013-05-23T10:02:09Z

Kordan: uploaded a new version of "File:multiselect.png"

File:integer.png

2013-05-23T10:01:19Z

Kordan: uploaded a new version of "File:integer.png"

File:fileupload.png

2013-05-23T10:00:53Z

Kordan: uploaded a new version of "File:fileupload.png"

File:checkbox.png

2013-05-23T10:00:05Z

Kordan: uploaded a new version of "File:checkbox.png"

File:boolean.png

2013-05-23T09:59:06Z

Kordan: uploaded a new version of "File:boolean.png"

File:autofill.png

2013-05-23T09:58:44Z

Kordan: uploaded a new version of "File:autofill.png"

File:age.png

2013-05-23T09:58:20Z

Kordan: uploaded a new version of "File:age.png"

File:date.png

2013-05-23T09:55:50Z

Kordan: uploaded a new version of "File:date.png"

File:date.png

2013-05-23T09:52:42Z

Kordan: uploaded a new version of "File:date.png"

Main features

2013-05-23T06:13:35Z

Kordan:

The main features of the survey module are:

* branching based on answer given by the users
* mandatory question answer
* user entry validation
* capability based access to survey elements
* permissions for groups of users feeding the same surveys submission
* pluggable question types
* pluggable format types
* pluggable master templates
* pluggable reports

Rationale

2013-05-23T05:34:22Z

Kordan:

The idea standing after the development of this module is to provide answers to the more frequent requirements of end users.

Their frequent requirements are:
==at element level==
* possibility to add custom question type matching specific needs
* question predefined value
* question level validation
* reduce, as much as possible, the range of possible answers
* mandatory questions
* have some typographic option to display elements in different ways
* tools to quickly reuse set a specific questions that never change in each survey
==at survey level==
* conditional branching
* force the user to provide a his/her own answer
* subset of questions available to teachers ONLY
* a way to allow a set of users to submit the same survey writing it at different times
* use captcha
* save a backup copy of each submitted survey each time it is modified in order to have the History of the record
* speed up form fill as much as it is possible
==at report level==
* custom reports
* export of submitted surveys

File:pagebreak.png

2013-05-22T14:44:48Z

Kordan:

File:label.png

2013-05-22T14:44:19Z

Kordan:

File:fieldset.png

2013-05-22T14:43:54Z

Kordan:

File:time.png

2013-05-22T14:43:10Z

Kordan: