diff --git a/admin/tests/behat/behat_admin.php b/admin/tests/behat/behat_admin.php index 1f439e64619..3c8acbc82bd 100644 --- a/admin/tests/behat/behat_admin.php +++ b/admin/tests/behat/behat_admin.php @@ -90,6 +90,8 @@ class behat_admin extends behat_base { * @Given /^the following config values are set as admin:$/ * @param TableNode $table */ + #[\core\attribute\example('And the following config values are set as admin: + | sendcoursewelcomemessage | 0 | enrol_manual |')] public function the_following_config_values_are_set_as_admin(TableNode $table) { if (!$data = $table->getRowsHash()) { diff --git a/admin/tool/generator/classes/local/testscenario/runner.php b/admin/tool/generator/classes/local/testscenario/runner.php index d35e0b9674d..1f4e0652374 100644 --- a/admin/tool/generator/classes/local/testscenario/runner.php +++ b/admin/tool/generator/classes/local/testscenario/runner.php @@ -22,6 +22,7 @@ use behat_base; use behat_course; use behat_general; use behat_user; +use core\attribute_helper; use Behat\Gherkin\Parser; use Behat\Gherkin\Lexer; use Behat\Gherkin\Keywords\ArrayKeywords; @@ -135,6 +136,14 @@ class runner { } } + /** + * Get all valid steps. + * @return array the valid steps. + */ + public function get_valid_steps(): array { + return array_values($this->validsteps); + } + /** * Scan a generator to get all valid steps. * @param behat_data_generators $generator the generator to scan. @@ -164,11 +173,17 @@ class runner { if (!$given) { return null; } - return (object)[ + $result = (object)[ 'given' => $given, 'name' => $method->getName(), 'generator' => $behatclass, + 'example' => null, ]; + $reference = $method->getDeclaringClass()->getName() . '::' . $method->getName(); + if ($attribute = attribute_helper::instance($reference, \core\attribute\example::class)) { + $result->example = (string) $attribute->example; + } + return $result; } /** diff --git a/admin/tool/generator/classes/output/stepsinformation.php b/admin/tool/generator/classes/output/stepsinformation.php new file mode 100644 index 00000000000..acda83a509c --- /dev/null +++ b/admin/tool/generator/classes/output/stepsinformation.php @@ -0,0 +1,78 @@ +. + +namespace tool_generator\output; +use templatable; +use tool_generator\local\testscenario\runner; + +/** + * Class stepsinformation + * + * @package tool_generator + * @copyright 2024 Ferran Recio + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class stepsinformation implements templatable, \renderable { + + /** + * Constructor. + * + * @param runner $runner the scenario runner + */ + public function __construct( + /** @var runner the runner instance. */ + public runner $runner + ) { + } + + /** + * Export this data so it can be used as the context for a mustache template (core/inplace_editable). + * + * @param \renderer_base $output typically, the renderer that's calling this function + * @return \stdClass data context for a mustache template + */ + public function export_for_template(\renderer_base $output): \stdClass { + $steps = []; + $validsteps = $this->runner->get_valid_steps(); + foreach ($validsteps as $step) { + $steps[] = (object)[ + 'given' => $this->highlight_params($step->given), + 'example' => $step->example, + ]; + } + return (object) [ + 'steps' => $steps, + ]; + } + + /** + * Highlight the parameters in a step. + * + * @param string $step the step to highlight + * @return string the step with the parameters highlighted + */ + private function highlight_params(string $step): string { + $step = htmlentities($step); + + // Highlight params starting with ":". + $step = preg_replace('/:(\w+)/', '$0', $step); + + // Highlight params enclosed in "(?P<...>)". + $step = preg_replace('/\(\?P<(\w+)>((?:[^"]|\\")*)\)/', '$0', $step); + + return $step; + } +} diff --git a/admin/tool/generator/lang/en/tool_generator.php b/admin/tool/generator/lang/en/tool_generator.php index 731c6b92ea1..2dff165b957 100644 --- a/admin/tool/generator/lang/en/tool_generator.php +++ b/admin/tool/generator/lang/en/tool_generator.php @@ -97,10 +97,14 @@ $string['sitesize_4'] = 'XL (~10GB; 1065 courses, created in ~5 hours)'; $string['sitesize_5'] = 'XXL (~20GB; 4177 courses, created in ~10 hours)'; $string['size'] = 'Size of course'; $string['smallfiles'] = 'Small files'; +$string['step_example'] = 'Step example:'; $string['targetcourse'] = 'Test target course'; $string['testscenario'] = 'Create testing scenarios'; $string['testscenario_description'] = 'Creating testing scenarios uses a limited feature files syntax to create all necessary elements to run a manual test.'; -$string['testscenario_filedesc'] = 'The upload feature files can only contain scenarios with core_data_generator steps. It is not yet compatible with scenario outlines. All scenarios will be executed at once but background steps will be ignored.'; +$string['testscenario_filedesc'] = 'The upload feature files can only contain scenarios with core_data_generator steps or some specific steps that do not require selenium. All scenarios will be executed at once except the ones with @cleanup tag.'; +$string['testscenario_filedesc_cleanup'] = 'Scenarios with @cleanup tag will be executed only if the "Execute" setting +is set to "Cleanup". To execute the cleanup via CLI, you can use the --cleanup option.'; +$string['testscenario_filedesc_list'] = 'This is the list of steps that can be used in the test scenario feature file:'; $string['testscenario_errorparsing'] = 'Error parsing feature file: {$a}'; $string['testscenario_file'] = 'Feature file'; $string['testscenario_invalidfile'] = 'The file format is not valid or contains invalid steps.'; diff --git a/admin/tool/generator/runtestscenario.php b/admin/tool/generator/runtestscenario.php index dfadef90957..4f2fb455b1a 100644 --- a/admin/tool/generator/runtestscenario.php +++ b/admin/tool/generator/runtestscenario.php @@ -25,6 +25,7 @@ use tool_generator\local\testscenario\runner; use tool_generator\form\featureimport; use tool_generator\output\parsingresult; +use tool_generator\output\stepsinformation; require(__DIR__ . '/../../../config.php'); require_once($CFG->libdir . '/adminlib.php'); @@ -54,7 +55,7 @@ try { die; } -echo $output->paragraph(get_string('testscenario_filedesc', 'tool_generator')); +echo $output->render(new stepsinformation($runner)); $mform = new featureimport(); diff --git a/admin/tool/generator/templates/stepsinformation.mustache b/admin/tool/generator/templates/stepsinformation.mustache new file mode 100644 index 00000000000..df2aa0e8806 --- /dev/null +++ b/admin/tool/generator/templates/stepsinformation.mustache @@ -0,0 +1,59 @@ +{{! + This file is part of Moodle - http://moodle.org/ + + Moodle is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + Moodle is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with Moodle. If not, see . +}} +{{! + @template tool_generator/stepsinformation + + Template with the available steps for the generator tool. + + Example context (json): + { + "steps": [ + { + "given": "I do something with :param", + "example": "example code" + }, + { + "given": "I do another thing with :param" + } + ] + } +}} +
+ {{< core/showmore }} + {{$collapsedcontent}} + {{#str}} testscenario_filedesc, tool_generator {{/str}} + {{/collapsedcontent}} + {{$expandedcontent}} +

{{#str}} testscenario_filedesc, tool_generator {{/str}}

+

{{#str}} testscenario_filedesc_cleanup, tool_generator {{/str}}

+

{{#str}} testscenario_filedesc_list, tool_generator {{/str}}

+
    + {{#steps}} +
  • + {{{given}}} + {{#example}} + + {{/example}} +
    • + {{/steps}} +
+ {{/expandedcontent}} + {{/core/showmore }} +
diff --git a/admin/tool/generator/tests/behat/testscenario.feature b/admin/tool/generator/tests/behat/testscenario.feature index eccbdd546e2..775acd93eb1 100644 --- a/admin/tool/generator/tests/behat/testscenario.feature +++ b/admin/tool/generator/tests/behat/testscenario.feature @@ -96,3 +96,16 @@ Feature: Create testing scenarios using generators And I should not see "Course cleanup" in the "course-listing" "region" And I navigate to "Users > Accounts > Browse list of users" in site administration And I should not see "Teacher Test1" + + Scenario: All available steps are listed in the tool to create testing scenarios + Given I log in as "admin" + When I navigate to "Development > Create testing scenarios" in site administration + Then I should see "This is the list of steps that can be used in the test scenario feature file" + And I should see "And the following \"activities\" exist" + And I should see "And \"5\" \"course enrolments\" exist with the following data" + And I should see "And the following \"course\" exists" + And I should see "And the following config values are set as admin" + And I should see "I enable \"subsection\" \"mod\" plugin" + And I should see "I disable \"page\" \"mod\" plugin" + And I should see "And the course \"Course test\" is deleted" + And I should see "And the user student1 is deleted" diff --git a/course/tests/behat/behat_course.php b/course/tests/behat/behat_course.php index 29be4f710ac..3de5741c50e 100644 --- a/course/tests/behat/behat_course.php +++ b/course/tests/behat/behat_course.php @@ -1159,6 +1159,7 @@ class behat_course extends behat_base { * @Given the course :coursefullname is deleted * @param string $coursefullname */ + #[\core\attribute\example('And the course "Course test" is deleted')] public function the_course_is_deleted($coursefullname) { delete_course($this->get_course_id($coursefullname), false); fix_course_sortorder(); diff --git a/lib/classes/attribute/example.php b/lib/classes/attribute/example.php new file mode 100644 index 00000000000..7d3e7661e53 --- /dev/null +++ b/lib/classes/attribute/example.php @@ -0,0 +1,33 @@ +. + +namespace core\attribute; + +/** + * An string attribute used to add an example of use of an object. + * + * @package core + * @copyright 2024 Ferran Recio + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +#[\Attribute] +class example { + public function __construct( + /** @var string the example text. */ + public readonly string $example, + ) { + } +} diff --git a/lib/tests/behat/behat_data_generators.php b/lib/tests/behat/behat_data_generators.php index c95b24b6f3f..5d716c54ca5 100644 --- a/lib/tests/behat/behat_data_generators.php +++ b/lib/tests/behat/behat_data_generators.php @@ -84,6 +84,10 @@ class behat_data_generators extends behat_base { * @param string $entitytype The name of the type entity to add * @param TableNode $data */ + #[\core\attribute\example('And the following "activities" exist: + | activity | name | intro | course | idnumber | section | visible | + | assign | Activity sample 1 | Test assignment | C1 | sample1 | 1 | 1 | + | assign | Activity sample 2 | Test assignment | C1 | sample2 | 1 | 0 |')] public function the_following_entities_exist($entitytype, TableNode $data) { if (isset($this->movedentitytypes[$entitytype])) { $entitytype = $this->movedentitytypes[$entitytype]; @@ -101,6 +105,10 @@ class behat_data_generators extends behat_base { * @param int $count * @param TableNode $data */ + #[\core\attribute\example('And "5" "course enrolments" exist with the following data: + | user | student[count] | + | course | C1 | + | role | student |')] public function the_following_repeated_entities_exist(string $entitytype, int $count, TableNode $data): void { $rows = $data->getRowsHash(); @@ -130,6 +138,12 @@ class behat_data_generators extends behat_base { * @param string $entitytype The name of the type entity to add * @param TableNode $data */ + #[\core\attribute\example('And the following "course" exists: + | fullname | Course test | + | shortname | C1 | + | category | 0 | + | numsections | 3 | + | initsections | 1 |')] public function the_following_entity_exists($entitytype, TableNode $data) { if (isset($this->movedentitytypes[$entitytype])) { $entitytype = $this->movedentitytypes[$entitytype]; diff --git a/lib/tests/behat/behat_general.php b/lib/tests/behat/behat_general.php index bd7d7d0a271..1d4b3ca0fb7 100644 --- a/lib/tests/behat/behat_general.php +++ b/lib/tests/behat/behat_general.php @@ -2366,6 +2366,7 @@ EOF; * @param string $plugin Plugin we look for * @param string $plugintype The type of the plugin */ + #[\core\attribute\example('I enable "subsection" "mod" plugin')] public function i_enable_plugin($plugin, $plugintype) { $class = core_plugin_manager::resolve_plugininfo_class($plugintype); $class::enable_plugin($plugin, true); @@ -2378,6 +2379,7 @@ EOF; * @param string $plugin Plugin we look for * @param string $plugintype The type of the plugin */ + #[\core\attribute\example('I disable "page" "mod" plugin')] public function i_disable_plugin($plugin, $plugintype) { $class = core_plugin_manager::resolve_plugininfo_class($plugintype); $class::enable_plugin($plugin, false); diff --git a/user/tests/behat/behat_user.php b/user/tests/behat/behat_user.php index 53c7ae234ef..6c04c3b0a98 100644 --- a/user/tests/behat/behat_user.php +++ b/user/tests/behat/behat_user.php @@ -58,6 +58,7 @@ class behat_user extends behat_base { * @Given the user :identifier is deleted * @param string $identifier */ + #[\core\attribute\example('And the user student1 is deleted')] public function the_user_is_deleted($identifier) { global $DB; $userid = $this->get_user_id_by_identifier($identifier);