Support and document usage with the Moodle App

.travis-app.dist.yml

@@ -0,0 +1,57 @@
+language: php
+
+addons:
+  postgresql: "10"
+
+services:
+  - mysql
+  - postgresql
+  - docker
+
+cache:
+  directories:
+    - $HOME/.composer/cache
+    - $HOME/.npm
+
+php:
+ - 7.3
+ - 7.4
+ - 8.0
+
+env:
+ global:
+  - MOODLE_BRANCH=MOODLE_311_STABLE
+  - MOODLE_BEHAT_IONIC_WWWROOT=http://localhost:8100
+  - MOODLE_BEHAT_DEFAULT_BROWSER=chrome
+ matrix:
+  - DB=pgsql
+  - DB=mysqli
+
+before_install:
+  - if [[ ${TRAVIS_PHP_VERSION:0:1} -gt 7 ]]; then pecl install xmlrpc-beta; fi
+  - echo 'max_input_vars=5000' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
+  # Don't disable xdebug if you want to get it used for code coverage.
+  - phpenv config-rm xdebug.ini
+  # Alternative (for Moodle 3.10 and up) is to use pcov. It can be installed using:
+  # - pecl install pcov
+  - cd ../..
+  - composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3
+  - export PATH="$(cd ci/bin; pwd):$(cd ci/vendor/bin; pwd):$PATH"
+  - docker run -d -p 8100:80 moodlehq/moodleapp:next-test
+  - moodle-plugin-ci add-plugin moodlehq/moodle-local_moodleappbehat --branch integration
+
+install:
+  - moodle-plugin-ci install
+
+script:
+  - moodle-plugin-ci phplint
+  - moodle-plugin-ci phpcpd
+  - moodle-plugin-ci phpmd
+  - moodle-plugin-ci codechecker
+  - moodle-plugin-ci validate
+  - moodle-plugin-ci savepoints
+  - moodle-plugin-ci mustache
+  - moodle-plugin-ci grunt
+  - moodle-plugin-ci phpdoc --fail-on-warning
+  - moodle-plugin-ci phpunit
+  - moodle-plugin-ci behat

docs/CHANGELOG.md

@@ -9,6 +9,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 The format of this change log follows the advice given at [Keep a CHANGELOG](http://keepachangelog.com).
 
 ## [Unreleased]
+### Added
+- Support and document usage with the Moodle App.
 
 ## [3.3.0] - 2022-06-28
 ### Added
@@ -228,7 +230,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
@@ -267,7 +269,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/Help.md

@@ -17,6 +17,7 @@ changed.  Also a good place to look for new goodies.
 * [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
 

docs/MoodleApp.md

@@ -0,0 +1,45 @@
+---
+layout: page
+title: Moodle App
+---
+
+In order to test plugins with mobile support, the only command that needs a special configuration is Behat. In particular, you need the following:
+
+- The Moodle App should be available during Behat runs and initialisation. One easy way to achieve this is using the [Moodle App Docker images](https://moodledev.io/docs/moodleapp/development/setup/docker-images), but you can configure it using a different approach if you prefer. What's important is that the app is reachable by the Behat scripts, and also make sure that it's running in the `test` environment so that the testing JavaScript in the app is available.
+- Related with the previous point, the Moodle instance needs to know where the app running. This can be configured using the `MOODLE_BEHAT_IONIC_WWWROOT` env variable during the `moodle-plugin-ci install` call.
+- The default browser in behat profiles must be `chrome`, or app scenarios will be ignored. This can also be configured using an env variable, called `MOODLE_BEHAT_DEFAULT_BROWSER`, during the `moodle-plugin-ci install` call. Be aware that using this variable will change the default browser, which is Firefox. If you still want to use Firefox for tests that are unrelated to the app, you can do so by running `moodle-plugin-ci behat --profile firefox`.
+- Finally, you need to install the [local_moodleappbehat](https://github.com/moodlehq/moodle-local_moodleappbehat) plugin; you can do this with the `add-plugin` command before running `install`. This plugin defines some Behat steps specifics to the app, if you want to learn more check out [Acceptance testing for the Moodle App](https://moodledev.io/docs/moodleapp/development/testing/acceptance-testing).
+
+For a complete example using these settings, you can look at the [.travis-app.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/.travis-app.dist.yml) or [gha-app.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha-app.dist.yml) files. You can look at the sections below to see how they differ from the originals.
+
+**Important:** Please notice that the configuration below only works with the development of the Moodle App and will be available in stable versions starting with the 4.1 release. If you want to use this setup against older versions, the same principles still apply but you'll need to tweak a couple of settings. In particular, you should be using the [local_moodlemobileapp](https://github.com/moodlehq/moodle-local_moodlemobileapp/) plugin instead and relying on stable tags in Docker images (for example, `latest-test`).
+
+## Github Actions
+
+```yaml
+# Add the moodlehq/moodleapp Docker image using the -test environment under services.
+moodleapp:
+  image: moodlehq/moodleapp:next-test
+  ports:
+      - 8100:80
+
+# Add the local_moodleappbehat plugin before running the install step.
+- name: Add local_moodleappbehat
+  run: moodle-plugin-ci add-plugin moodlehq/moodle-local_moodleappbehat --branch integration
+
+# Add a couple of environment variables in the install step.
+MOODLE_BEHAT_IONIC_WWWROOT: http://localhost:8100
+MOODLE_BEHAT_DEFAULT_BROWSER: chrome
+```
+
+## Travis
+
+```yaml
+# Add a couple of global environment variables.
+- MOODLE_BEHAT_IONIC_WWWROOT=http://localhost:8100
+- MOODLE_BEHAT_DEFAULT_BROWSER=chrome
+
+# Start a moodlehq/moodleapp Docker container using the -test environment, and add the local_moodleappbehat plugin, before install.
+- docker run -d -p 8100:80 moodlehq/moodleapp:next-test
+- moodle-plugin-ci add-plugin moodlehq/moodle-local_moodleappbehat --branch integration
+```

docs/index.md

@@ -81,6 +81,12 @@ Start manual](https://docs.github.com/en/actions/quickstart#viewing-your-workflo
 useful. Now whenever you push commits to your plugin repo or it gets a new
 pull request, GitHub will run a build to make sure nothing broke.
 
+### Moodle App
+
+If your plugin has mobile support, the only thing that requires any special configuration is running Behat tests. You can use the [.travis-app.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/.travis-app.dist.yml) or [gha-app.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha-app.dist.yml) files to get started.
+
+To learn more, check out the [dedicated page about the Moodle App](MoodleApp.md).
+
 ### Getting more of CI
 
 Next steps on your continuous build journey may include:

gha-app.dist.yml

@@ -0,0 +1,118 @@
+name: Moodle Plugin CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-18.04
+
+    services:
+      postgres:
+        image: postgres:10
+        env:
+          POSTGRES_USER: 'postgres'
+          POSTGRES_HOST_AUTH_METHOD: 'trust'
+        ports:
+          - 5432:5432
+        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3
+      mariadb:
+        image: mariadb:10
+        env:
+          MYSQL_USER: 'root'
+          MYSQL_ALLOW_EMPTY_PASSWORD: "true"
+          MYSQL_CHARACTER_SET_SERVER: "utf8mb4"
+          MYSQL_COLLATION_SERVER: "utf8mb4_unicode_ci"
+        ports:
+          - 3306:3306
+        options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3
+      moodleapp:
+        image: moodlehq/moodleapp:next-test
+        ports:
+          - 8100:80
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['7.3', '7.4', '8.0']
+        moodle-branch: ['MOODLE_311_STABLE']
+        database: [pgsql, mariadb]
+
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v2
+        with:
+          path: plugin
+
+      - name: Setup PHP ${{ matrix.php }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: ${{ matrix.extensions }}
+          ini-values: max_input_vars=5000
+          # none to use phpdbg fallback. Specify pcov (Moodle 3.10 and up) or xdebug to use them instead.
+          coverage: none
+
+      - name: Initialise moodle-plugin-ci
+        run: |
+          composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3
+          echo $(cd ci/bin; pwd) >> $GITHUB_PATH
+          echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH
+          sudo locale-gen en_AU.UTF-8
+          echo "NVM_DIR=$HOME/.nvm" >> $GITHUB_ENV
+
+      - name: Add local_moodleappbehat
+        run: moodle-plugin-ci add-plugin moodlehq/moodle-local_moodleappbehat --branch integration
+
+      - 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 }}
+          MOODLE_BEHAT_IONIC_WWWROOT: http://localhost:8100
+          MOODLE_BEHAT_DEFAULT_BROWSER: chrome
+
+      - name: PHP Lint
+        if: ${{ always() }}
+        run: moodle-plugin-ci phplint
+
+      - name: PHP Copy/Paste Detector
+        continue-on-error: true # This step will show errors but will not fail
+        if: ${{ always() }}
+        run: moodle-plugin-ci phpcpd
+
+      - name: PHP Mess Detector
+        continue-on-error: true # This step will show errors but will not fail
+        if: ${{ always() }}
+        run: moodle-plugin-ci phpmd
+
+      - name: Moodle Code Checker
+        if: ${{ always() }}
+        run: moodle-plugin-ci codechecker --max-warnings 0
+
+      - name: Moodle PHPDoc Checker
+        if: ${{ always() }}
+        run: moodle-plugin-ci phpdoc
+
+      - name: Validating
+        if: ${{ always() }}
+        run: moodle-plugin-ci validate
+
+      - name: Check upgrade savepoints
+        if: ${{ always() }}
+        run: moodle-plugin-ci savepoints
+
+      - name: Mustache Lint
+        if: ${{ always() }}
+        run: moodle-plugin-ci mustache
+
+      - name: Grunt
+        if: ${{ always() }}
+        run: moodle-plugin-ci grunt --max-lint-warnings 0
+
+      - name: PHPUnit tests
+        if: ${{ always() }}
+        run: moodle-plugin-ci phpunit --fail-on-warning
+
+      - name: Behat features
+        if: ${{ always() }}
+        run: moodle-plugin-ci behat --profile chrome

gha.dist.yml

@@ -22,7 +22,6 @@ jobs:
           MYSQL_ALLOW_EMPTY_PASSWORD: "true"
           MYSQL_CHARACTER_SET_SERVER: "utf8mb4"
           MYSQL_COLLATION_SERVER: "utf8mb4_unicode_ci"
-
         ports:
           - 3306:3306
         options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3
@@ -58,8 +57,7 @@ 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 }}

res/template/config.php.txt

@@ -27,6 +27,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}}';
@@ -38,13 +41,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,20 +34,22 @@ public function createContents(AbstractDatabase $database, $dataDir)
     {
         $template  = file_get_contents(__DIR__.'/../../res/template/config.php.txt');
         $variables = [
-            '{{DBTYPE}}'          => $database->type,
-            '{{DBLIBRARY}}'       => $database->library,
-            '{{DBHOST}}'          => $database->host,
-            '{{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,
+            '{{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') ?: 'firefox',
+            '{{BEHATIONICWWWROOT}}'   => getenv('MOODLE_BEHAT_IONIC_WWWROOT') ?: '',
+            '{{EXTRACONFIG}}'         => self::PLACEHOLDER,
         ];
 
         return str_replace(array_keys($variables), array_values($variables), $template);

tests/Fixture/example-config.php

@@ -27,6 +27,9 @@
 $CFG->noemailever    = true;
 $CFG->noreplyaddress = 'noreply@localhost.local';
 
+// App settings.
+$CFG->behat_ionic_wwwroot = '';
+
 // PHPUnit settings.
 $CFG->phpunit_prefix   = 'phpu_';
 $CFG->phpunit_dataroot = '/path/to/moodledata/phpu_moodledata';
@@ -45,6 +48,10 @@
         'browser' => 'chrome',
         'wd_host' => 'http://localhost:4444/wd/hub',
     ],
+    'firefox' => [
+        'browser' => 'firefox',
+        'wd_host' => 'http://localhost:4444/wd/hub',
+    ],
 ];
 
 // Extra config.