Merge pull request #176 from NoelDeMartin/moodle-app

Support and document usage with the Moodle App

Author: stronk7

.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

@@ -26,6 +26,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.
 - Updated project dependencies to current [moodle-cs](https://github.com/moodlehq/moodle-cs) and [moodle-local_moodlecheck](https://github.com/moodlehq/moodle-local_moodlecheck) versions.
 
+### 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.
@@ -429,7 +432,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
@@ -468,7 +471,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, so make sure that you're using the correct browser. If you're setting the `MOODLE_APP` variable, the default browser should already be Chrome; but you can set it explicitly using the `--profile` flag otherwise.
+
+For 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() }}