Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401]

Base class for data generators component support for acceptance testing.

Copyright: 2012 David MonllaĆ³
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 626 lines (23 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 2 files
 lib/behat/behat_base.php
 lib/testing/generator/lib.php

Defines 1 class


Class: behat_generator_base  - X-Ref

Class to quickly create Behat test data using component data generators.

There is a subclass of class for each component that wants to be able to
generate entities using the Behat step
Given the following "entity types" exist:
| test | data |

For core entities, the entity type is like "courses" or "users" and
generating those is handled by behat_core_generator. For other components
the entity type is like "mod_quiz > User override" and that is handled by
behat_mod_quiz_generator defined in mod/quiz/tests/generator/behat_mod_quiz_generator.php.

The types of entities that can be generated are described by the array returned
by the {@link get_generateable_entities()} method. The list in
{@link behat_core_generator} is a good (if complex) example.

How things work is best explained with a few examples. All this is implemented
in the {@link generate_items()} method below, if you want to see every detail of
how it works.

Simple example from behat_core_generator:
'users' => [
'datagenerator' => 'user',
'required' => ['username'],
],
The steps performed are:

1. 'datagenerator' => 'user' means that the word used in the method names below is 'user'.

2. Because 'required' is present, check the supplied data exists 'username' column is present
in the supplied data table and if not display an error.

3. Then for each row in the table as an array $elementdata (array keys are column names)
and process it as follows

4. (Not used in this example.)

5. If the method 'preprocess_user' exists, then call it to update $elementdata.
(It does, in this case it sets the password to the username, if password was not given.)

We then do one of 4 things:

6a. If there is a method 'process_user' we call it. (It doesn't for user,
but there are other examples like process_enrol_user() in behat_core_generator.)

6b. (Not used in this example.)

6c. Else, if testing_data_generator::create_user exists, we call it with $elementdata. (it does.)

6d. If none of these three things work. an error is thrown.

To understand the missing steps above, consider the example from behat_mod_quiz_generator:
'group override' => [
'datagenerator' => 'override',
'required' => ['quiz', 'group'],
'switchids' => ['quiz' => 'quiz', 'group' => 'groupid'],
],
Processing is as above, except that:

1. Note 'datagenerator' is 'override' (not group_override). 'user override' maps to the
same datagenerator. This works fine.

4. Because 'switchids' is present, human-readable data in the table gets converted to ids.
They array key 'group' refers to a column which may be present in the table (it will be
here because it is required, but it does not have to be in general). If that column
is present and contains a value, then the method matching name like get_group_id() is
called with the value from that column in the data table. You must implement this
method. You can see several examples of this sort of method below.

If that method returns a group id, then $elementdata['group'] is unset and
$elementdata['groupid'] is set to the result of the get_group_id() call. 'groupid' here
because of the definition is 'switchids' => [..., 'group' => 'groupid'].
If get_group_id() cannot find the group, it should throw a helpful exception.

Similarly, 'quiz' (the quiz name) is looked up with a call to get_quiz_id(). Here, the
new array key set matches the old one removed. This is fine.

6b. We are in a plugin, so before checking whether testing_data_generator::create_override
exists we first check whether mod_quiz_generator::create_override() exists. It does,
and this is what gets called.

This second example shows why the get_..._id methods for core entities are in this base
class, not in behat_core_generator. Plugins may need to look up the ids of
core entities.

behat_core_generator is defined in lib/behat/classes/behat_core_generator.php
and for components, behat_..._generator is defined in tests/generator/behat_..._generator.php
inside the plugin. For example behat_mod_quiz_generator is defined in
mod/quiz/tests/generator/behat_mod_quiz_generator.php.

__construct(string $component)   X-Ref
Constructor.

param: string $component component name, to make error messages more readable.

get_available_generators()   X-Ref
Get the list of available generators for this class.

return: array

generate_items(string $generatortype, TableNode $data, bool $singular = false)   X-Ref
Do the work to generate an entity.

This is called by {@link behat_data_generators::the_following_entities_exist()}.

param: string    $generatortype The name of the entity to create.
param: TableNode $data from the step.
param: bool      $singular Whether there is only one record and it is pivotted

name_for_errors(string $entitytype)   X-Ref
Helper for formatting error messages.

param: string $entitytype entity type without prefix, e.g. 'frog'.
return: string either 'frog' for core entities, or 'mod_mymod > frog' for components.

get_gradecategory_id($fullname)   X-Ref
Gets the grade category id from the grade category fullname

param: string $fullname the grade category name.
return: int corresponding id.

get_user_id($username)   X-Ref
Gets the user id from it's username.

param: string $username
return: int

get_userfrom_id(string $username)   X-Ref
Gets the user id from it's username.

param: string $username
return: int

get_userto_id(string $username)   X-Ref
Gets the user id from it's username.

param: string $username
return: int

get_role_id($roleshortname)   X-Ref
Gets the role id from it's shortname.

param: string $roleshortname
return: int

get_category_id($idnumber)   X-Ref
Gets the category id from it's idnumber.

param: string $idnumber
return: int

get_course_id($shortname)   X-Ref
Gets the course id from it's shortname.

param: string $shortname
return: int

get_activity_id(string $idnumber)   X-Ref
Gets the course cmid for the specified activity based on the activity's idnumber.

Note: this does not check the module type, only the idnumber.

param: string $idnumber
return: int

get_group_id($idnumber)   X-Ref
Gets the group id from it's idnumber.

param: string $idnumber
return: int

get_grouping_id($idnumber)   X-Ref
Gets the grouping id from it's idnumber.

param: string $idnumber
return: int

get_cohort_id($idnumber)   X-Ref
Gets the cohort id from it's idnumber.

param: string $idnumber
return: int

get_outcome_id($shortname)   X-Ref
Gets the outcome item id from its shortname.

param: string $shortname
return: int

get_scale_id($name)   X-Ref
Get the id of a named scale.

param: string $name the name of the scale.
return: int the scale id.

get_questioncategory_id($name)   X-Ref
Get the id of a named question category (must be globally unique).
Note that 'Top' is a special value, used when setting the parent of another
category, meaning top-level.

param: string $name the question category name.
return: int the question category id.

get_context($levelname, $contextref)   X-Ref
Gets the internal context id from the context reference.

The context reference changes depending on the context
level, it can be the system, a user, a category, a course or
a module.

param: string $levelname The context level string introduced by the test writer
param: string $contextref The context reference introduced by the test writer
return: context

get_contact_id($username)   X-Ref
Gets the contact id from it's username.

param: string $username
return: int

get_externalbackpack_id($backpackweburl)   X-Ref
Gets the external backpack id from it's backpackweburl.

param: string $backpackweburl
return: mixed

get_cm_by_activity_name(string $activity, string $identifier)   X-Ref
Get a coursemodule from an activity name or idnumber.

param: string $activity
param: string $identifier
return: cm_info