MoodleDocs - User contributions [en]

Running acceptance test

2021-04-26T19:15:16Z

Sbourget: Updated chromedriver link

== Short version ==

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

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

==== 1. Background ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

To run all the tests in one .feature file:

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

To run a single scenario:

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

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

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

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

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

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

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

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

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

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

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

<code>
php admin/tool/behat/cli/init.php --add-core-features-to-theme=clean
</code>
The first time init runs can be time consuming as it creates a paralell set of tables to core, i.e. bh_user,bh_assign etc. After init the tests can be run with the alternative theme as follows.
<code>
vendor/bin/behat --suite=classic --tags="@enrol_foobar"
</code>

If there is no --suite= parameter it will fall back to the default boost theme. No = or quotes needed around the theme name.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Alternative way of running three Selenium servers in parallel:

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

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

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

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

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

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

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

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

Behat should now run as before, but faster.

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

1. Go through all the steps from above

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

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

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

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

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

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

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

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

=== Increasing timeouts ===

You may see errors such as:

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

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

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

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

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

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

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

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

== Trouble shooting ==

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

=== Tests are failing ===

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

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

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

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

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

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

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

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

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

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

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

Authentication plugins

2017-05-09T18:08:45Z

Sbourget:

==Introduction==

This page first gives an '''overview''' of the ''authentication process'' and then explains how ''authentication modules'' can be '''created''' using hooks to take over from the native authentication in Moodle.
=== Overview of Moodle authentication process ===
[[File:1.9.11_login_element.png|203px||thumb|right|The login UI element in Moodle 1.9]]The authentication use case in Moodle starts when a user clicks on the Login link in the UI or if they try to access a protected page. There are two broad classes of authentication plugins, the regular type where moodle handles the password and ones where the password is handled by a 3rd party page eg SAML, OpenID etc.

For the regular plugins the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) is displayed. OR, if a system administrator has set the Alternate Login URL on the "Manage authentication" page, that URL will be displayed.
# A user enters their credentials and submits the form.
# The handler code in <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> is a valid object) and, if not, sends them back to the login page with an error message. Otherwise, it figures out where to send the user based on their original page request, whether their password is expired, etc., and redirects them there.

For the 3rd party auth plugins the process could look like this (eg CAS, SAML, OpenID etc):
# Access a protected page but isn't logged in, so moodle calls <tt>pre_loginpage_hook()</tt> on each enabled plugin, which may redirect to the 3rd party login page
# Or if they go directly to the login page moodle calls <tt>loginpage_hook()</tt> on each enabled plugin, which may redirect to the 3rd party login page
# The user enters their credentials and authenticates on the 3rd party page
# The remote authentication service redirects back to moodle with an assertion, such as a single use token or encrypted response in a query param
# The auth plugin now validates the token or decrypts the assertion, does any other checking as required and then logs the user in using <tt>complete_user_login($user)</tt>. If this happens inside <tt>pre_loginpage_hook()</tt> then the user continues on their way, or if inside <tt>loginpage_hook()</tt> or another custom page then the plugin should redirect to the wantsurl.

Note that in this scenario above <tt>user_login($username, $password)</tt> is never called and should probably return false.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 Google / Facebook / Messenger Oauth2 Authentication plugin]

==Template==
Please see Moodle '''none''' authentication plugin (auth/none), it's the perfect plugin template to start with.

==Naming convention==
==File structure==
# Choose a name for your plugin. We'll use 'sentry' as an example below; change it to whatever name you have chosen.
# Under your Moodle installation root, create the directory <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> file, and create or override additional functions based on your plugin's requirements.
# Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication". You will see your plugin in the list, appearing as <nowiki>[[auth_sentrytitle]]</nowiki>. You can enable it and move it up and down in the order. '''At this point, with the plugin enabled, your plugin is registered and will be used by Moodle in its authentication process.'''
# If you don't like seeing <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> in the plugin class. You might find it convenient to use the 'db' plugin as a model for this. The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the <tt>mdl_config_plugins</tt> table in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# It gets a list of enabled authentication plugins.
# It looks up the username in the mdl_user table to see if they are allowed to log in, and which authentication plugin handles their login requests. (This will be the plugin that handled their first-ever login request.)
# It creates a user object, which will contain the data from <tt>mdl_user</tt> if the username is known; if not, it will be an empty object.
# It does the following with the authentication plugin (note that for a username unknown to Moodle, it will do these steps for each authenticated plugin until one succeeds or it has tried them all):
## Calls the <tt>user_login()</tt> function provided by that plugin, which returns a boolean value based on whether the credentials authenticate or not. If the result is false (not authenticated), skips the rest of the steps below and continues to the next plugin.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
This must be rewritten by plugin to return boolean value, returns true if the username and password work and false if they are wrong or don't exist.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
Returns true if this authentication plugin is "internal". Internal plugins use password hashes from Moodle user table for authentication.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database. This function automatically returns the opposite boolean of what is_internal() returns. Returning true means MD5 password hashes will be stored in the user table. Returning false means flag 'not_cached' will be stored there instead.

; '''Return type''' : boolean
; '''Default return value''' : !$this->is_internal()

=== <tt>is_synchronised_with_external()</tt>===
Indicates if moodle should automatically update internal user records with data from external sources using the information from get_userinfo() method. This function automatically returns the opposite boolean of what is_internal() returns.

; '''Return type''' : boolean
; '''Default return value''' : !$this->is_internal()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>can_signup()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
Prints a form for configuring this authentication plugin. It's called from admin/auth.php, and outputs a full page with a form for configuring this plugin.
This function has been deprecated in Moodle 3.3. You should use the [[Admin_settings]] API instead. For more information see [https://tracker.moodle.org/browse/MDL-12689]

=== <tt>validate_form($form, $err)</tt>===
Validate form data.
This function has been deprecated in Moodle 3.3. You should use the [[Admin_settings]] API instead. For more information see [https://tracker.moodle.org/browse/MDL-12689]

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.
This function has been deprecated in Moodle 3.3. You should use the [[Admin_settings]] API instead. For more information see [https://tracker.moodle.org/browse/MDL-12689]

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>pre_loginpage_hook()</tt>===
Hook for overriding behaviour of prior to redirecting to the login page, eg redirecting to an external login url for SAML or OpenID authentication. If you implement this you should also implement loginpage_hook as the user may go directly to the login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>postlogout_hook()</tt>===
This method replace the prelogout_hook method to avoid authentication plugins redirects before the user logout event being triggered.
At the moment the only authentication plugin using this method is CAS (SSO).

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

=== <tt>can_be_manually_set()</tt> ===
This function was introduced in the base class and returns false by default. If overriden by an authentication plugin to return true, the authentication plugin will be able to be manually set for users. For example, when bulk uploading users you will be able to select it as the authentication method they use.

=== <tt> loginpage_idp_list() </tt> ===
Override this method and return a list of Identification Providers (IDPs) that your authentication plugin supports. An array of associative arrays containing url, icon and name for the IDP. These will be displayed on the login page and in the login block.

=== <tt>pre_user_login_hook(&$user)</tt>===
This method is called from authenticate_user_login() right after the user object is generated. This gives the auth plugin an option to make modification to the user object before the verification process starts.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Lesson Improvements

2016-04-28T11:36:36Z

Sbourget:

Proposed Lesson 3.X Improvements

'''Overview:'''
The lesson module is a very powerful but complex module. The goal of this proposal is to simplify the module without sacrificing flexibility or functionality. A current analysis of the open issues for the lesson module show that the can be grouped into 3 categories:

*Feature requests to add support for features currently provided by core APIs but are not currently implemented in lesson
*Bug fixes for current lesson functionality provided by non-standard APIs
*New features and improvements

'''What this proposal is trying to fix:'''
The lesson module is considered an advanced module due to the numerous settings that control its behaviors. One major goal of revamping the lesson module should be to make it simpler to use for teachers. This should be done without removing functionality, but making it easier / more intuitive to set up. This can be accomplished a few different ways.
*By removing redundant settings from the module
*By moving some functionality to independent moodle plugins
*By converting different parts of the lesson module to use standard moodle APIs

'''Proposed changes:'''
'''Phase I: (Simplify the lesson codebase / reduce the number of options when creating a new lesson)'''

In order to simplify the user interface, several unnecessary settings can be removed from the lesson module:
*“Maximum number of answers” - This setting is only used to limit the number of answers on multiple choice and matching authoring pages. Most other modules in moodle allow the activity author to add as many answers as needed while creating the activity. (MDL-52874)
*“Password” - There are two settings required to enable a password in a lesson activity. One setting to enable the password, another to actually set the password. Other activities in Moodle that use a password only require a single field (MDL-53143)

In order to simplify the lesson codebase and reduce a significant amount of duplicate code, several lesson features should be converted to separate moodle plugins.

*“Media File / File pop-up” - The lesson module has a feature that allows a teacher to post a single file in a fake block displayed within that specific lesson activity. It makes sense to create a generic block to allow teacher to post any number of files anywhere in moodle and then convert the “media file” feature in lesson to use this block. This should eliminate the confusion about the media popup in lesson. (MDL-29437, MDL-30333)
*Lesson Menu - The lesson module has a couple of configuration settings to determine when a navigation menu should be displayed to the student. There is also a feature request to make this block moveable which would require an additional setting on the lesson configuration screen. It makes sense to create a separate lesson navigation block and remove the left menu settings from the lesson module. Lessons would be converted to use this block instead. (MDL-31920, MDL-22752)

'''Phase II: (Implement a lesson overview page)'''
Once the lesson codebase has been cleaned up, A few changes can be made to improve the way a lesson is presented to the student. The biggest proposed change is to add a lesson overview page at the start of each lesson activity. (this is similar to how the quiz module works.) This overview page would display the following information:
*Lesson Description (if set)
*Lesson available from date (if set)
*Lesson available until date (if set)
*Time limit (if set)
*Grading method for lesson (no grade, maximum points)
*Whether retakes are allowed.
*How retakes are scored
(It would also display a start lesson / resume lesson button depending on the current state of the students attempt)

The lesson overview page would only be displayed to users who have the lesson:view capability (MDL-14448) and the start lesson button would only be available to users with the lesson:attempt capability (MDL-20087). These improvements should also resolve issues MDL-51735 and MDL-49480.

Once these tasks have been completed it should be easy to improve the reporting for the lesson module. Specifically MDL-19948 allowing students to review their answers choices in lesson. This could be provided as a link on the lesson overview page for users who have completed the lesson and have the lesson:viewmyattempt capability.

'''Phase III: (Implement partial question bank support)'''
Allowing the Lesson module to fully utilize the questions API (MDL-18954) will resolve a significant number of lesson bugs and feature requests (MDL-34927, MDL-47548, MDL-50256, MDL-43111, MDL-39874, MDL-39261, MDL-39655, MDL-45798, etc)

The moodle lesson activity currently has functionality to import questions stored in Moodle XML format. There currently isn’t a mechanism however to export a lesson into Moodle XML format. The improvement proposed here is to create a utility that will convert / export all existing lesson pages into standard moodle question types to make them available in the moodle question bank. It should be possible to map the existing lesson page types to the following Moodle question types:
*Lesson Essay -> Essay
*Lesson Matching -> Matching
*Lesson T/F -> True / False
*Lesson Multichoice -> Multichoice
*Lesson Content page -> Description
*Lesson Numerical -> Numeric
*Lesson Short Answer -> Short answer (Note: the core short answer question type may need to be extended to support the regular expression option available in it’s lesson counterpart)
*Cluster / subcluster -> Random question (Not Exported)

'''Phase IV: (Full Question bank support)'''
Implement a new editing page for lesson allowing teachers to choose questions from the question bank and allow teachers to specify page / question sequencing. All existing lessons would be converted to use the question bank in place of lesson's custom page types.

Currently lessons are made up of pages that contain a single question or piece of content. How the user answers these questions dictate which page the user will navigate to next. Rather than displaying a single question per page, This proposal seeks to instead have a lesson constructed of pages and each page constructed of one or more questions. The current approach for lesson sequencing would be changed as follows:

*Each page would allow path selection based on a grade percentage or range (0%, 50%, 100%, etc)
*Each page would allow path selection based on one or more manual links (For non-auto graded pages like description or essay)
*Pages that contain a single question would allow path selection based on the user answer. (Note, this would only be available to specific question types specifically multiple choice, true/false, numeric, and short answer. Each question type would have to announce support for this functionality. This would allow existing lessons to continue working as-is.)

Lesson Improvements

2016-02-16T22:34:03Z

Sbourget:

Proposed Lesson 3.X Improvements

'''Overview:'''
The lesson module is a very powerful but complex module. The goal of this proposal is to simplify the module without sacrificing flexibility or functionality. A current analysis of the open issues for the lesson module show that the can be grouped into 3 categories:

*Feature requests to add support for features currently provided by core APIs but are not currently implemented in lesson
*Bug fixes for current lesson functionality provided by non-standard APIs
*New features and improvements

'''What this proposal is trying to fix:'''
The lesson module is considered an advanced module due to the numerous settings that control its behaviors. One major goal of revamping the lesson module should be to make it simpler to use for teachers. This should be done without removing functionality, but making it easier / more intuitive to set up. This can be accomplished a few different ways.
*By removing redundant settings from the module
*By moving some functionality to independent moodle plugins
*By converting different parts of the lesson module to use standard moodle APIs

'''Proposed changes:'''
'''Phase I: (Simplify the lesson codebase / reduce the number of options when creating a new lesson)'''

In order to simplify the user interface, several unnecessary settings can be removed from the lesson module:
*“Maximum number of answers” - This setting is only used to limit the number of answers on multiple choice and matching authoring pages. Most other modules in moodle allow the activity author to add as many answers as needed while creating the activity. (MDL-52874)
*“Password” - There are two settings required to enable a password in a lesson activity. One setting to enable the password, another to actually set the password. Other activities in Moodle that use a password only require a single field (MDL-53143)

In order to simplify the lesson codebase and reduce a significant amount of duplicate code, several lesson features should be converted to separate moodle plugins.

*“Media File / File pop-up” - The lesson module has a feature that allows a teacher to post a single file in a fake block displayed within that specific lesson activity. It makes sense to create a generic block to allow teacher to post any number of files anywhere in moodle and then convert the “media file” feature in lesson to use this block. This should eliminate the confusion about the media popup in lesson. (MDL-29437, MDL-30333)
*Lesson Menu - The lesson module has a couple of configuration settings to determine when a navigation menu should be displayed to the student. There is also a feature request to make this block moveable which would require an additional setting on the lesson configuration screen. It makes sense to create a separate lesson navigation block and remove the left menu settings from the lesson module. Lessons would be converted to use this block instead. (MDL-31920, MDL-22752)

'''Phase II: (Implement a lesson overview page)'''
Once the lesson codebase has been cleaned up, A few changes can be made to improve the way a lesson is presented to the student. The biggest proposed change is to add a lesson overview page at the start of each lesson activity. (this is similar to how the quiz module works.) This overview page would display the following information:
*Lesson Description (if set)
*Lesson available from date (if set)
*Lesson available until date (if set)
*Time limit (if set)
*Grading method for lesson (no grade, maximum points)
*Whether retakes are allowed.
*How retakes are scored
(It would also display a start lesson / resume lesson button depending on the current state of the students attempt)

The lesson overview page would only be displayed to users who have the lesson:view capability (MDL-14448) and the start lesson button would only be available to users with the lesson:attempt capability (MDL-20087). These improvements should also resolve issues MDL-51735 and MDL-49480.

Once these tasks have been completed it should be easy to improve the reporting for the lesson module. Specifically MDL-19948 allowing students to review their answers choices in lesson. This could be provided as a link on the lesson overview page for users who have completed the lesson and have the lesson:viewmyattempt capability.

'''Phase III: (Implement partial question bank support)'''
Allowing the Lesson module to fully utilize the questions API (MDL-18954) will resolve a significant number of lesson bugs and feature requests (MDL-34927, MDL-47548, MDL-50256, MDL-43111, MDL-39874, MDL-39261, MDL-39655, MDL-45798, etc) While this proposal seeks to improve the situation, it will not address all of the current issues.

The moodle lesson activity currently has functionality to import questions stored in Moodle XML format. There currently isn’t a mechanism however to export a lesson into Moodle XML format. The improvement proposed here is to create a utility that will convert / export all existing lesson pages into standard moodle question types to make them available in the moodle question bank. It should be possible to map the existing lesson page types to the following moodle question types:
*Lesson Essay -> Essay
*Lesson Matching -> Matching
*Lesson T/F -> True / False
*Lesson Multichoice -> Multichoice
*Lesson Content page -> Description
*Lesson Numerical -> Numeric
*Lesson Short Answer -> Short answer (Note: the core short answer question type may need to be extended to support the regular expression option available in it’s lesson counterpart)
*Cluster / subcluster -> Random question (Not Exported)

'''Phase IV: (Future Full Question bank support)'''
Implement a new editing page for lesson allowing teachers to choose questions from the question bank and allow teachers to specify question sequencing
*Allow path selection based on a grade percentage or range (0%, 50%, 100%, etc)
*Allow path selection based on a manual link (For non-auto graded pages like description or essay)

Lesson Improvements

2016-02-16T22:33:26Z

Sbourget: Created page with "Moodle Lesson Module Improvement Plan '''Overview:''' The lesson module is a very powerful but complex module. The goal of this proposal is to simplify the module without sa..."

Moodle Lesson Module Improvement Plan

'''Overview:'''
The lesson module is a very powerful but complex module. The goal of this proposal is to simplify the module without sacrificing flexibility or functionality. A current analysis of the open issues for the lesson module show that the can be grouped into 3 categories:

*Feature requests to add support for features currently provided by core APIs but are not currently implemented in lesson
*Bug fixes for current lesson functionality provided by non-standard APIs
*New features and improvements

'''What this proposal is trying to fix:'''
The lesson module is considered an advanced module due to the numerous settings that control its behaviors. One major goal of revamping the lesson module should be to make it simpler to use for teachers. This should be done without removing functionality, but making it easier / more intuitive to set up. This can be accomplished a few different ways.
*By removing redundant settings from the module
*By moving some functionality to independent moodle plugins
*By converting different parts of the lesson module to use standard moodle APIs

'''Proposed changes:'''
'''Phase I: (Simplify the lesson codebase / reduce the number of options when creating a new lesson)'''

In order to simplify the user interface, several unnecessary settings can be removed from the lesson module:
*“Maximum number of answers” - This setting is only used to limit the number of answers on multiple choice and matching authoring pages. Most other modules in moodle allow the activity author to add as many answers as needed while creating the activity. (MDL-52874)
*“Password” - There are two settings required to enable a password in a lesson activity. One setting to enable the password, another to actually set the password. Other activities in Moodle that use a password only require a single field (MDL-53143)

In order to simplify the lesson codebase and reduce a significant amount of duplicate code, several lesson features should be converted to separate moodle plugins.

*“Media File / File pop-up” - The lesson module has a feature that allows a teacher to post a single file in a fake block displayed within that specific lesson activity. It makes sense to create a generic block to allow teacher to post any number of files anywhere in moodle and then convert the “media file” feature in lesson to use this block. This should eliminate the confusion about the media popup in lesson. (MDL-29437, MDL-30333)
*Lesson Menu - The lesson module has a couple of configuration settings to determine when a navigation menu should be displayed to the student. There is also a feature request to make this block moveable which would require an additional setting on the lesson configuration screen. It makes sense to create a separate lesson navigation block and remove the left menu settings from the lesson module. Lessons would be converted to use this block instead. (MDL-31920, MDL-22752)

'''Phase II: (Implement a lesson overview page)'''
Once the lesson codebase has been cleaned up, A few changes can be made to improve the way a lesson is presented to the student. The biggest proposed change is to add a lesson overview page at the start of each lesson activity. (this is similar to how the quiz module works.) This overview page would display the following information:
*Lesson Description (if set)
*Lesson available from date (if set)
*Lesson available until date (if set)
*Time limit (if set)
*Grading method for lesson (no grade, maximum points)
*Whether retakes are allowed.
*How retakes are scored
(It would also display a start lesson / resume lesson button depending on the current state of the students attempt)

The lesson overview page would only be displayed to users who have the lesson:view capability (MDL-14448) and the start lesson button would only be available to users with the lesson:attempt capability (MDL-20087). These improvements should also resolve issues MDL-51735 and MDL-49480.

Once these tasks have been completed it should be easy to improve the reporting for the lesson module. Specifically MDL-19948 allowing students to review their answers choices in lesson. This could be provided as a link on the lesson overview page for users who have completed the lesson and have the lesson:viewmyattempt capability.

'''Phase III: (Implement partial question bank support)'''
Allowing the Lesson module to fully utilize the questions API (MDL-18954) will resolve a significant number of lesson bugs and feature requests (MDL-34927, MDL-47548, MDL-50256, MDL-43111, MDL-39874, MDL-39261, MDL-39655, MDL-45798, etc) While this proposal seeks to improve the situation, it will not address all of the current issues.

The moodle lesson activity currently has functionality to import questions stored in Moodle XML format. There currently isn’t a mechanism however to export a lesson into Moodle XML format. The improvement proposed here is to create a utility that will convert / export all existing lesson pages into standard moodle question types to make them available in the moodle question bank. It should be possible to map the existing lesson page types to the following moodle question types:
*Lesson Essay -> Essay
*Lesson Matching -> Matching
*Lesson T/F -> True / False
*Lesson Multichoice -> Multichoice
*Lesson Content page -> Description
*Lesson Numerical -> Numeric
*Lesson Short Answer -> Short answer (Note: the core short answer question type may need to be extended to support the regular expression option available in it’s lesson counterpart)
*Cluster / subcluster -> Random question (Not Exported)

'''Phase IV: (Future Full Question bank support)'''
Implement a new editing page for lesson allowing teachers to choose questions from the question bank and allow teachers to specify question sequencing
*Allow path selection based on a grade percentage or range (0%, 50%, 100%, etc)
*Allow path selection based on a manual link (For non-auto graded pages like description or essay)

sandbox

2016-02-16T22:26:13Z

Sbourget:

For playing around in....
a