Support and document usage with the Moodle App

.github/workflows/test.yml

@@ -86,12 +86,8 @@ jobs:
             moodle-branch: 'MOODLE_400_STABLE'
           - php: '8.0'
             moodle-branch: 'MOODLE_311_STABLE'
-          - php: '7.4'
-            moodle-branch: 'MOODLE_310_STABLE'
           - php: '7.4'
             moodle-branch: 'MOODLE_39_STABLE'
-          - php: '7.4'
-            moodle-branch: 'MOODLE_38_STABLE'
 
     steps:
     - name: Check out repository code
@@ -127,6 +123,7 @@ jobs:
         IGNORE_PATHS: 'ignore'
         IGNORE_NAMES: 'ignore_name.php'
         MUSTACHE_IGNORE_NAMES: 'broken.mustache'
+        MOODLE_APP: 'true'
 
     - name: Run Integration tests
       env:
@@ -145,6 +142,7 @@ jobs:
         moodle-plugin-ci phpunit --verbose --coverage-text --fail-on-warning
         moodle-plugin-ci behat --profile default
         moodle-plugin-ci behat --profile chrome
+        moodle-plugin-ci behat --profile firefox --tags="@local_ci&&~@app"
 
   buildphar:
     name: Build moodle-plugin-ci.phar
@@ -240,6 +238,7 @@ jobs:
         IGNORE_PATHS: 'ignore'
         IGNORE_NAMES: 'ignore_name.php'
         MUSTACHE_IGNORE_NAMES: 'broken.mustache'
+        MOODLE_APP: 'true'
 
     - name: Run Integration tests (PHAR)
       env:
@@ -258,3 +257,4 @@ jobs:
         php build/moodle-plugin-ci.phar phpunit --verbose --coverage-text --fail-on-warning
         php build/moodle-plugin-ci.phar behat --profile default
         php build/moodle-plugin-ci.phar behat --profile chrome
+        php build/moodle-plugin-ci.phar behat --profile firefox --tags="@local_ci&&~@app"

.travis.dist.yml

@@ -28,6 +28,8 @@ env:
  global:
   - PGVER=13
   - MOODLE_BRANCH=MOODLE_402_STABLE
+  # Uncomment this to run Behat tests using the Moodle App.
+  # - MOODLE_APP=true
  matrix:
   - DB=pgsql
   - DB=mysqli

.travis.yml

@@ -46,7 +46,7 @@ before_install:
     fi
 
 install:
-  - moodle-plugin-ci install -vvv
+  - MOODLE_APP=true moodle-plugin-ci install -vvv
 
 script:
   # This is basically "integration" testing.
@@ -63,6 +63,7 @@ script:
   - moodle-plugin-ci phpunit --verbose --coverage-text --fail-on-warning
   - moodle-plugin-ci behat --profile default
   - moodle-plugin-ci behat --profile chrome
+  - moodle-plugin-ci behat --profile firefox --tags="@local_ci&&~@app"
 
 jobs:
   include:
@@ -94,6 +95,6 @@ jobs:
     # Last stable with highest supported PHP version.
     - php: 8.2
       env: MOODLE_BRANCH=MOODLE_402_STABLE
-    # And oldest stable supported (with lowest supported PHP version).
+    # And older stable supported (with lowest supported PHP version).
     - php: 7.4
-      env: MOODLE_BRANCH=MOODLE_38_STABLE
+      env: MOODLE_BRANCH=MOODLE_39_STABLE

docs/CHANGELOG.md

@@ -23,6 +23,9 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 
   To avoid that problem it's recommended to to add the `libonig5` package to the `travis.yml` file. For a working example, please reference the updated `.travis.dist.yml`file.
 
+### Added
+- Support and document usage with the [Moodle App](MoodleApp.md).
+
 ## [4.1.8] - 2023-10-20
 ### Changed
 - Updated project dependencies to current [moodle-cs](https://github.com/moodlehq/moodle-cs) version.
@@ -426,7 +429,7 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 
 ### Fixed
 - `moodle-plugin-ci validate` now only regards required language strings as present if they are assigned to the
-  `$string` array. Before, other array variables were accepted although Moodle would not recognise them.  
+  `$string` array. Before, other array variables were accepted although Moodle would not recognise them.
 
 ### Added
 - `moodle-plugin-ci install` now provides an option `--no-init` to skip initialization of the Behat and PHPUnit
@@ -465,7 +468,7 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
   PHP compatibility issues for the **currently** running PHP version.  This makes it important to run this command
   on your lowest and highest supported PHP version.  EG: on PHP 5.6 and 7.1.
 - `moodle-plugin-ci validate` command now validates tags in Behat feature files.  EG: mod_forum should have @mod
-  and @mod_forum tags in each feature file. 
+  and @mod_forum tags in each feature file.
 - The `.travis.dist.yml` now installs Version 2 of this tool.
 - Updated Moodle coding standard to v2.7.0.
 

docs/GHAFileExplained.md

@@ -124,12 +124,16 @@ jobs:
       # Other env vars are available for install, namely:
       #   - DB_USER / DB_PASS / DB_NAME / DB_HOST / DB_PORT: used
       #     by install to feed the corresponding --db-xxxx options.
+      #   - MOODLE_APP: used to install dependencies to run Behat tests
+      #     using the Moodle App.
       - name: Install moodle-plugin-ci
         run: |
           moodle-plugin-ci install --plugin ./plugin --db-host=127.0.0.1
         env:
           DB: ${{ matrix.database }}
           MOODLE_BRANCH: ${{ matrix.moodle-branch }}
+          # Uncomment this to run Behat tests using the Moodle App.
+          # MOODLE_APP: 'true'
 
       # Steps that are run for the purpose of testing.  Any of these steps
       # can be re-ordered or removed to your liking.  And of course, you can

docs/Help.md

@@ -16,6 +16,7 @@ Always a good idea to check the [change log](CHANGELOG.md) if something suddenly
 * [Ignoring files](IgnoringFiles.md): how to ignore files that might be causing failures.
 * [Generating code coverage](CodeCoverage.md): how to generate code coverage of your plugin.
 * [CLI commands and options](CLI.md): the available `moodle-plugin-ci` commands and their options.
+* [Moodle App](MoodleApp.md): how to configure `moodle-plugin-ci` to test plugins with mobile support.
 
 ## Test steps quick start
 
@@ -84,7 +85,10 @@ There are few important options that you may want to use:
 - The suite option allows you to set the theme to use for behat test. If
   not specified, the default theme is used, e.g. usage: `--suite boost`
 - The profile option allows you to set the browser driver to use,
-  default is Firefox. If you need Chrome, set `--profile chrome`.
+  default is Firefox (or Chrome when `MOODLE_APP` is set). If you need a specific browser,
+  use `--profile chrome` or `--profile firefox`.
+- The tags option allows you to specify which scenarios to run filtered by tags,
+  default is the tag with the plugin's component name, e.g. usage: `--tags="@local_myplugin~@ciskip"`
 
 ## Upgrade guides
 

docs/MoodleApp.md

@@ -0,0 +1,20 @@
+---
+layout: page
+title: Moodle App
+---
+
+In order to test plugins with mobile support, the only command that needs a special configuration is `behat`.
+
+In practice, you only need to set the `MOODLE_APP` env variable to `true`, and all the dependencies will be configured during the `install` command. You can also configure the behaviour of [Acceptance testing for the Moodle App](https://moodledev.io/general/app/development/testing/acceptance-testing) using the following env variables:
+
+- `MOODLE_APP_DOCKER_IMAGE`: Tag of [the Moodle App Docker image](https://moodledev.io/general/app/development/setup/docker-images) to use for running the app. The default value is `moodlehq/moodleapp:latest-test`.
+- `MOODLE_APP_BEHAT_PLUGIN_PROJECT`: Project in github to use for installing the plugin with Behat steps specific to the Moodle App. The default value is `moodlehq/moodle-local_moodleappbehat`. This variable will be ignored if `MOODLE_APP_BEHAT_PLUGIN_REPOSITORY` is set.
+- `MOODLE_APP_BEHAT_PLUGIN_REPOSITORY`: Repository url to use for installing the plugin with Behat steps specific to the Moodle App. By default, the github repository defined in `MOODLE_APP_BEHAT_PLUGIN_PROJECT` will be used.
+- `MOODLE_APP_BEHAT_PLUGIN_BRANCH`: Branch of the repository to use for installing the plugin with Behat steps specific to the Moodle App. The default value is `latest`.
+- `MOODLE_BEHAT_IONIC_WWWROOT`: Value to use in `$CFG->behat_ionic_wwwroot`. The default value is `http://localhost:8100`. This value should only be used if `MOODLE_APP` is not set, and the Moodle App dependencies are configured manually.
+
+Finally, keep in mind that mobile tests only run on chrome device, so make sure to use it with the `--profile` flag.
+
+For a specific examples, look at the [gha.dist.yml](GHAFileExplained.md) or [.travis.dist.yml](TravisFileExplained.md) files, and uncomment the lines mentioning the app.
+
+**Important:** Please notice that `MOODLE_APP` only works starting with version 4.1 of the app. If you want to use this setup against older versions, you'll have to use `MOODLE_BEHAT_IONIC_WWWROOT` and configure the dependencies manually (installing the plugin, launching the docker image, etc.).

docs/TravisFileExplained.md

@@ -52,6 +52,9 @@ env:
   - PGVER=13
 # This line determines which version branch of Moodle to test against.
   - MOODLE_BRANCH=MOODLE_402_STABLE
+# Uncomment this to run Behat tests using the Moodle App.
+#   - MOODLE_APP=true
+
 # This matrix is used for testing against multiple databases.  So for
 # each version of PHP being tested, one build will be created for each
 # database listed here.  EG: for PHP 7.4, one build will be created

docs/index.md

@@ -167,6 +167,7 @@ Next steps on your continuous build journey may include:
 * Reviewing the [help documentation](Help.md) to further improve and customize your build.
 * Resolve any build errors you may currently have. Get to that ever rewarding Green Build status.
 * Show off your build status by adding the build status badge to your plugin's README file.
+* Learn how to [configure CI for your mobile plugins in the Moodle App](MoodleApp.md).
 * Write new tests to increase your code coverage.
 * Contribute to this repo if you have improvement idea or found an issue.
 * Enjoy your favorite beverage because you no longer have to waste time manually testing your plugin!

gha.dist.yml

@@ -59,11 +59,12 @@ jobs:
           echo "NVM_DIR=$HOME/.nvm" >> $GITHUB_ENV
 
       - name: Install moodle-plugin-ci
-        run: |
-          moodle-plugin-ci install --plugin ./plugin --db-host=127.0.0.1
+        run: moodle-plugin-ci install --plugin ./plugin --db-host=127.0.0.1
         env:
           DB: ${{ matrix.database }}
           MOODLE_BRANCH: ${{ matrix.moodle-branch }}
+          # Uncomment this to run Behat tests using the Moodle App.
+          # MOODLE_APP: 'true'
 
       - name: PHP Lint
         if: ${{ !cancelled() }}

res/template/config.php.txt

@@ -29,6 +29,9 @@ $CFG->debugdisplay = 1;
 $CFG->noemailever    = true;
 $CFG->noreplyaddress = 'noreply@localhost.local';
 
+// App settings.
+$CFG->behat_ionic_wwwroot = '{{BEHATIONICWWWROOT}}';
+
 // PHPUnit settings.
 $CFG->phpunit_prefix   = 'phpu_';
 $CFG->phpunit_dataroot = '{{PHPUNITDATAROOT}}';
@@ -40,13 +43,17 @@ $CFG->behat_wwwroot       = '{{BEHATWWWROOT}}';
 $CFG->behat_faildump_path = '{{BEHATDUMP}}';
 $CFG->behat_profiles      = [
     'default' => [
-        'browser' => 'firefox',
+        'browser' => '{{BEHATDEFAULTBROWSER}}',
         'wd_host' => '{{BEHATWDHOST}}',
     ],
     'chrome' => [
         'browser' => 'chrome',
         'wd_host' => '{{BEHATWDHOST}}',
     ],
+    'firefox' => [
+        'browser' => 'firefox',
+        'wd_host' => '{{BEHATWDHOST}}',
+    ],
 ];
 
 {{EXTRACONFIG}}

src/Bridge/MoodleConfig.php

@@ -34,21 +34,23 @@ public function createContents(AbstractDatabase $database, string $dataDir): str
     {
         $template  = file_get_contents(__DIR__ . '/../../res/template/config.php.txt');
         $variables = [
-            '{{DBTYPE}}'          => $database->type,
-            '{{DBLIBRARY}}'       => $database->library,
-            '{{DBHOST}}'          => $database->host,
-            '{{DBPORT}}'          => $database->port,
-            '{{DBNAME}}'          => $database->name,
-            '{{DBUSER}}'          => $database->user,
-            '{{DBPASS}}'          => $database->pass,
-            '{{WWWROOT}}'         => 'http://localhost/moodle',
-            '{{DATAROOT}}'        => $dataDir,
-            '{{PHPUNITDATAROOT}}' => $dataDir . '/phpu_moodledata',
-            '{{BEHATDATAROOT}}'   => $dataDir . '/behat_moodledata',
-            '{{BEHATDUMP}}'       => $dataDir . '/behat_dump',
-            '{{BEHATWWWROOT}}'    => getenv('MOODLE_BEHAT_WWWROOT') ?: 'http://localhost:8000',
-            '{{BEHATWDHOST}}'     => getenv('MOODLE_BEHAT_WDHOST') ?: 'http://localhost:4444/wd/hub',
-            '{{EXTRACONFIG}}'     => self::PLACEHOLDER,
+            '{{DBTYPE}}'              => $database->type,
+            '{{DBLIBRARY}}'           => $database->library,
+            '{{DBHOST}}'              => $database->host,
+            '{{DBPORT}}'              => $database->port,
+            '{{DBNAME}}'              => $database->name,
+            '{{DBUSER}}'              => $database->user,
+            '{{DBPASS}}'              => $database->pass,
+            '{{WWWROOT}}'             => 'http://localhost/moodle',
+            '{{DATAROOT}}'            => $dataDir,
+            '{{PHPUNITDATAROOT}}'     => $dataDir . '/phpu_moodledata',
+            '{{BEHATDATAROOT}}'       => $dataDir . '/behat_moodledata',
+            '{{BEHATDUMP}}'           => $dataDir . '/behat_dump',
+            '{{BEHATWWWROOT}}'        => getenv('MOODLE_BEHAT_WWWROOT') ?: 'http://localhost:8000',
+            '{{BEHATWDHOST}}'         => getenv('MOODLE_BEHAT_WDHOST') ?: 'http://localhost:4444/wd/hub',
+            '{{BEHATDEFAULTBROWSER}}' => getenv('MOODLE_BEHAT_DEFAULT_BROWSER') ?: (getenv('MOODLE_APP') ? 'chrome' : 'firefox'),
+            '{{BEHATIONICWWWROOT}}'   => getenv('MOODLE_APP') ? 'http://localhost:8100' : (getenv('MOODLE_BEHAT_IONIC_WWWROOT') ?: ''),
+            '{{EXTRACONFIG}}'         => self::PLACEHOLDER,
         ];
 
         return str_replace(array_keys($variables), array_values($variables), $template);

src/Command/BehatCommand.php

@@ -144,7 +144,13 @@ private function startServerProcesses(InputInterface $input): void
         }
 
         // Start docker container using desired image.
-        if ($input->getOption('profile') === 'chrome') {
+        $profile = $input->getOption('profile');
+
+        if ($profile === 'default') {
+            $profile = getenv('MOODLE_BEHAT_DEFAULT_BROWSER') ?: (getenv('MOODLE_APP') ? 'chrome' : 'firefox');
+        }
+
+        if ($profile === 'chrome') {
             $image = $this->seleniumChromeImage;
         } elseif ($this->usesLegacyPhpWebdriver()) {
             $image = $this->seleniumLegacyFirefoxImage;

src/Installer/InstallerFactory.php

@@ -43,6 +43,13 @@ class InstallerFactory
     public function addInstallers(InstallerCollection $installers): void
     {
         $installers->add(new MoodleInstaller($this->execute, $this->database, $this->moodle, new MoodleConfig(), $this->repo, $this->branch, $this->dataDir));
+
+        if (getenv('MOODLE_APP')) {
+            $this->pluginsDir = $this->pluginsDir ?? 'moodle-plugin-ci-plugins';
+
+            $installers->add(new MoodleAppInstaller($this->execute, $this->pluginsDir));
+        }
+
         $installers->add(new PluginInstaller($this->moodle, $this->plugin, $this->pluginsDir, $this->dumper));
         $installers->add(new VendorInstaller($this->moodle, $this->plugin, $this->execute, $this->nodeVer));
 

src/Installer/MoodleAppInstaller.php

@@ -0,0 +1,81 @@
+<?php
+
+/*
+ * This file is part of the Moodle Plugin CI package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * Copyright (c) 2018 Blackboard Inc. (http://www.blackboard.com)
+ * License http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace MoodlePluginCI\Installer;
+
+use MoodlePluginCI\Process\Execute;
+use MoodlePluginCI\Validate;
+use Symfony\Component\Filesystem\Filesystem;
+use Symfony\Component\Process\Process;
+
+/**
+ * Moodle App Installer.
+ */
+class MoodleAppInstaller extends AbstractInstaller
+{
+    private Execute $execute;
+    private string $pluginsDir;
+
+    public function __construct(Execute $execute, string $pluginsDir)
+    {
+        $this->execute    = $execute;
+        $this->pluginsDir = $pluginsDir;
+    }
+
+    public function install(): void
+    {
+        $this->addEnv('MOODLE_APP', 'true');
+
+        // Launch docker image.
+        $this->getOutput()->step('Launch Moodle App docker image');
+
+        $image = getenv('MOODLE_APP_DOCKER_IMAGE') ?: 'moodlehq/moodleapp:latest-test';
+
+        $this->execute->mustRun([
+            'docker',
+            'run',
+            '-d',
+            '--rm',
+            '--name=moodleapp',
+            '-p',
+            '8100:80',
+            $image,
+        ]);
+
+        // Clone plugin.
+        $this->getOutput()->step('Clone Moodle App Behat plugin');
+
+        $pluginProject    = getenv('MOODLE_APP_BEHAT_PLUGIN_PROJECT') ?: 'moodlehq/moodle-local_moodleappbehat';
+        $pluginRepository = getenv('MOODLE_APP_BEHAT_PLUGIN_REPOSITORY') ?: sprintf('https://github.com/%s.git', $pluginProject);
+        $pluginBranch     = getenv('MOODLE_APP_BEHAT_PLUGIN_BRANCH') ?: 'latest';
+        $filesystem       = new Filesystem();
+        $validate         = new Validate();
+        $command          = [
+            'git',
+            'clone',
+            '--depth',
+            '1',
+            '--branch',
+            $pluginBranch,
+            $pluginRepository,
+        ];
+
+        $filesystem->mkdir($this->pluginsDir);
+        $storageDir = realpath($validate->directory($this->pluginsDir));
+        $this->execute->mustRun(new Process($command, $storageDir, null, null, null));
+    }
+
+    public function stepCount(): int
+    {
+        return 2;
+    }
+}

tests/Bridge/MoodlePluginTest.php

@@ -125,7 +125,9 @@ public function testGetFiles()
         $files    = $plugin->getFiles($finder);
         $expected = [
             $this->pluginDir . '/classes/math.php',
+            $this->pluginDir . '/classes/output/mobile.php',
             $this->pluginDir . '/db/access.php',
+            $this->pluginDir . '/db/mobile.php',
             $this->pluginDir . '/db/upgrade.php',
             $this->pluginDir . '/lang/en/local_ci.php',
             $this->pluginDir . '/lib.php',
@@ -151,7 +153,9 @@ public function testGetRelativeFiles()
         $plugin   = new MoodlePlugin($this->pluginDir);
         $expected = [
             'classes/math.php',
+            'classes/output/mobile.php',
             'db/access.php',
+            'db/mobile.php',
             'db/upgrade.php',
             'lang/en/local_ci.php',
             'lib.php',