diff --git a/development/extensions/tutorial_testing.rst b/development/extensions/tutorial_testing.rst index 6e52102c..433d7c8e 100644 --- a/development/extensions/tutorial_testing.rst +++ b/development/extensions/tutorial_testing.rst @@ -824,435 +824,30 @@ Copy the following into the ``tests.yml`` file: name: Tests - env: - EXTNAME: acme/demo # Your extension vendor/package name - SNIFF: 1 # Run code sniffer on your code? 1 or 0 - IMAGE_ICC: 1 # Run icc profile sniffer on your images? 1 or 0 - EPV: 1 # Run EPV (Extension Pre Validator) on your code? 1 or 0 - EXECUTABLE_FILES: 1 # Run check for executable files? 1 or 0 - PHPBB_BRANCH: 3.3.x # The phpBB branch to run tests on - on: - push: - branches: # Run tests when commits are pushed to these branches in your repo - - master - - develop - pull_request: # Run tests when pull requests are made on these branches in your repo - branches: - - master - - develop + push: # Run tests when commits are pushed to these branches in your repo, + branches: # ... or remove this branches section to run tests on all your branches + - main # Main production branch + - master # Legacy or alternative main branch + - dev/* # Any feature branches under "dev/", e.g., dev/new-feature + + pull_request: # Run tests when pull requests are made on these branches in your repo, + branches: # ... or remove this branches section to run tests on all your branches + - main + - master + - dev/* jobs: - # START Basic Checks Job (EPV, code sniffer, images check, etc.) - basic-checks: - runs-on: ubuntu-20.04 - strategy: - matrix: - include: - - php: '7.2' - db: "none" - NOTESTS: 1 - - name: PHP ${{ matrix.php }} - ${{ matrix.db }} - - steps: - - name: Checkout phpBB - uses: actions/checkout@v3 - with: - repository: phpbb/phpbb - ref: ${{ env.PHPBB_BRANCH }} - path: phpBB3 - - - name: Checkout extension - uses: actions/checkout@v3 - with: - path: phpBB3/phpBB/ext/${{ env.EXTNAME }} - - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ matrix.php }} - extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, mysqli, sqlite, pdo_sqlite, intl, gd, exif, iconv, sqlsrv, pdo_sqlsrv, ldap - coverage: none - - - name: Setup environment for phpBB - env: - DB: ${{ matrix.db }} - PHP_VERSION: ${{ matrix.php }} - NOTESTS: '1' - run: .github/setup-phpbb.sh $DB $PHP_VERSION $NOTESTS - working-directory: ./phpBB3 - - - name: Setup EPV - if: ${{ env.EPV != 0 }} - run: composer require phpbb/epv:dev-master --dev --no-interaction --ignore-platform-reqs - working-directory: ./phpBB3/phpBB - - - name: Run code sniffer - if: ${{ env.SNIFF != 0 }} - env: - NOTESTS: '1' - run: .github/ext-sniff.sh $EXTNAME $NOTESTS - working-directory: ./phpBB3 - - - name: Check image ICC profiles - if: ${{ env.IMAGE_ICC != 0 }} - run: .github/check-image-icc-profiles.sh - working-directory: ./phpBB3 - - - name: Check executable files - if: ${{ env.EXECUTABLE_FILES != 0 }} - run: .github/ext-check-executable-files.sh ./ $EXTNAME - working-directory: ./phpBB3 - - - name: Run EPV - if: ${{ env.EPV != 0 }} - run: phpBB/vendor/bin/EPV.php run --dir="phpBB/ext/$EXTNAME/" - working-directory: ./phpBB3 - # END Basic Checks Job - - # START MySQL and MariaDB Job - mysql-tests: - runs-on: ubuntu-20.04 - strategy: - matrix: - include: - - php: '7.2' - db: "mariadb:10.1" - - php: '7.2' - db: "mariadb:10.2" - - php: '7.2' - db: "mariadb:10.3" - - php: '7.2' - db: "mariadb:10.4" - - php: '7.2' - db: "mariadb:10.5" - - php: '7.2' - db: "mysql:5.6" - db_alias: "MyISAM Tests" - MYISAM: 1 - - php: '7.2' - db: "mysql:5.6" - - php: '7.2' - db: "mysql:5.7" - - php: '7.3' - db: "mysql:5.7" - - php: '7.4' - db: "mysql:5.7" - - php: '7.4' - db: "mysql:8.0" - - php: '8.0' - db: "mysql:5.7" - - php: '8.1' - db: "mysql:5.7" - - php: '8.2' - db: "mysql:5.7" - - name: PHP ${{ matrix.php }} - ${{ matrix.db_alias != '' && matrix.db_alias || matrix.db }} - - services: - mysql: - image: ${{ matrix.db }} - env: - MYSQL_ALLOW_EMPTY_PASSWORD: yes - MYSQL_DATABASE: phpbb_tests - ports: - - 3306:3306 - options: >- - --health-cmd="mysqladmin ping" - --health-interval=10s - --health-timeout=5s - --health-retries=3 - - redis: - image: redis - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - - 6379:6379 - - steps: - - name: Checkout phpBB - uses: actions/checkout@v3 - with: - repository: phpbb/phpbb - ref: ${{ env.PHPBB_BRANCH }} - path: phpBB3 - - - name: Checkout extension - uses: actions/checkout@v3 - with: - path: phpBB3/phpBB/ext/${{ env.EXTNAME }} - - - id: database-type - env: - MATRIX_DB: ${{ matrix.db }} - run: | - db=$(echo "${MATRIX_DB%%:*}") - echo "db=$db" >> $GITHUB_OUTPUT - - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ matrix.php }} - extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, mysqli, sqlite, pdo_sqlite, intl, gd, exif, iconv, sqlsrv, pdo_sqlsrv, ldap - coverage: none - - - name: Setup environment for phpBB - env: - DB: ${{steps.database-type.outputs.db}} - PHP_VERSION: ${{ matrix.php }} - NOTESTS: '0' - run: .github/setup-phpbb.sh $DB $PHP_VERSION ${NOTESTS:-0} - working-directory: ./phpBB3 - - - name: Setup database - env: - DB: ${{steps.database-type.outputs.db}} - MYISAM: ${{ matrix.MYISAM != 1 && '0' || '1' }} - run: .github/setup-database.sh $DB $MYISAM - working-directory: ./phpBB3 - - - name: Setup PHPUnit files - run: mkdir -p phpBB/ext/$EXTNAME/.github && cp .github/phpunit* $_ - working-directory: ./phpBB3 - - - name: Run unit tests - env: - DB: ${{steps.database-type.outputs.db}} - run: phpBB/vendor/bin/phpunit --configuration phpBB/ext/$EXTNAME/.github/phpunit-$DB-github.xml --bootstrap ./tests/bootstrap.php - working-directory: ./phpBB3 - # END MySQL and MariaDB Job - - # START PostgreSQL Job - postgres-tests: - runs-on: ubuntu-20.04 - strategy: - matrix: - include: - - php: '7.2' - db: "postgres:9.5" - - php: '7.2' - db: "postgres:9.6" - - php: '7.2' - db: "postgres:10" - - php: '7.2' - db: "postgres:11" - - php: '7.2' - db: "postgres:12" - - php: '7.2' - db: "postgres:13" - - php: '7.3' - db: "postgres:13" - - php: '7.4' - db: "postgres:13" - - php: '8.0' - db: "postgres:12" - - php: '8.0' - db: "postgres:13" - - php: '8.1' - db: "postgres:14" - - php: '8.2' - db: "postgres:14" - - name: PHP ${{ matrix.php }} - ${{ matrix.db }} - - services: - postgres: - image: ${{ matrix.db != 'postgres:9.5' && matrix.db != 'postgres:9.6' && matrix.db != 'postgres:10' && matrix.db != 'postgres:11' && matrix.db != 'postgres:12' && matrix.db != 'postgres:13' && 'postgres:10' || matrix.db }} - env: - POSTGRES_HOST: localhost - POSTGRES_USER: postgres - POSTGRES_PASSWORD: postgres - ports: - - 5432:5432 - options: >- - -v /var/run/postgresql:/var/run/postgresql - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 - - redis: - image: redis - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - - 6379:6379 - - steps: - - name: Checkout phpBB - uses: actions/checkout@v3 - with: - repository: phpbb/phpbb - ref: ${{ env.PHPBB_BRANCH }} - path: phpBB3 - - - name: Checkout extension - uses: actions/checkout@v3 - with: - path: phpBB3/phpBB/ext/${{ env.EXTNAME }} - - - id: database-type - env: - MATRIX_DB: ${{ matrix.db }} - run: | - db=$(echo "${MATRIX_DB%%:*}") - echo "db=$db" >> $GITHUB_OUTPUT - - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ matrix.php }} - extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, mysqli, sqlite, pdo_sqlite, intl, gd, exif, iconv, sqlsrv, pdo_sqlsrv, ldap - coverage: none - - - name: Setup environment for phpBB - env: - DB: ${{steps.database-type.outputs.db}} - PHP_VERSION: ${{ matrix.php }} - NOTESTS: '0' - run: .github/setup-phpbb.sh $DB $PHP_VERSION ${NOTESTS:-0} - working-directory: ./phpBB3 - - - name: Setup database - env: - DB: ${{steps.database-type.outputs.db}} - MYISAM: '0' - run: .github/setup-database.sh $DB $MYISAM - working-directory: ./phpBB3 - - - name: Setup PHPUnit files - run: mkdir -p phpBB/ext/$EXTNAME/.github && cp .github/phpunit* $_ - working-directory: ./phpBB3 - - - name: Run unit tests - env: - DB: ${{steps.database-type.outputs.db}} - run: phpBB/vendor/bin/phpunit --configuration phpBB/ext/$EXTNAME/.github/phpunit-$DB-github.xml --bootstrap ./tests/bootstrap.php - working-directory: ./phpBB3 - # END PostgreSQL Job - - # START Other Tests Job (SQLite 3 and mssql) - other-tests: - runs-on: ubuntu-20.04 - strategy: - matrix: - include: - - php: '7.2' - db: "sqlite3" - - php: '7.2' - db: "mcr.microsoft.com/mssql/server:2017-latest" - db_alias: 'MSSQL 2017' - - php: '7.2' - db: "mcr.microsoft.com/mssql/server:2019-latest" - db_alias: 'MSSQL 2019' - - name: PHP ${{ matrix.php }} - ${{ matrix.db_alias != '' && matrix.db_alias || matrix.db }} - - services: - mssql: - image: ${{ matrix.db != 'mcr.microsoft.com/mssql/server:2017-latest' && matrix.db != 'mcr.microsoft.com/mssql/server:2019-latest' && 'mcr.microsoft.com/mssql/server:2017-latest' || matrix.db }} - env: - SA_PASSWORD: "Pssw0rd_12" - ACCEPT_EULA: "y" - ports: - - 1433:1433 - options: >- - --health-cmd="/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'Pssw0rd_12' -Q \"Use [master]; CREATE DATABASE [phpbb_tests] COLLATE Latin1_General_CI_AS\" || exit 1" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - --health-start-period 10s - - redis: - image: redis - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - - 6379:6379 - - steps: - - name: Checkout phpBB - uses: actions/checkout@v3 - with: - repository: phpbb/phpbb - ref: ${{ env.PHPBB_BRANCH }} - path: phpBB3 - - - name: Checkout extension - uses: actions/checkout@v3 - with: - path: phpBB3/phpBB/ext/${{ env.EXTNAME }} - - - id: database-type - env: - MATRIX_DB: ${{ matrix.db }} - run: | - if [ $MATRIX_DB == 'mcr.microsoft.com/mssql/server:2017-latest' ] || [ $MATRIX_DB == 'mcr.microsoft.com/mssql/server:2019-latest' ] - then - db='mssql' - else - db=$(echo "${MATRIX_DB%%:*}") - fi - echo "db=$db" >> $GITHUB_OUTPUT - - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ matrix.php }} - extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, mysqli, sqlite, pdo_sqlite, intl, gd, exif, iconv, sqlsrv, pdo_sqlsrv, ldap - coverage: none - - - name: Setup environment for phpBB - env: - DB: ${{steps.database-type.outputs.db}} - PHP_VERSION: ${{ matrix.php }} - NOTESTS: '0' - run: .github/setup-phpbb.sh $DB $PHP_VERSION ${NOTESTS:-0} - working-directory: ./phpBB3 - - - name: Setup database - env: - DB: ${{steps.database-type.outputs.db}} - MYISAM: '0' - run: .github/setup-database.sh $DB $MYISAM - working-directory: ./phpBB3 - - - name: Setup PHPUnit files - run: mkdir -p phpBB/ext/$EXTNAME/.github && cp .github/phpunit* $_ - working-directory: ./phpBB3 - - - name: Run unit tests - env: - DB: ${{steps.database-type.outputs.db}} - run: phpBB/vendor/bin/phpunit --configuration phpBB/ext/$EXTNAME/.github/phpunit-$DB-github.xml --bootstrap ./tests/bootstrap.php - working-directory: ./phpBB3 - # END Other Tests Job + call-tests: + name: Extension tests + uses: phpbb-extensions/test-framework/.github/workflows/tests.yml@3.3.x + with: + EXTNAME: acme/demo # Your extension vendor/package name (required) .. note:: You must change the ``EXTNAME`` variable to your extension's name (as you defined it in - your composer.json file) in the ``env`` section at the top of this file: - - .. code-block:: yaml - - env: - EXTNAME: acme/demo # Your extension vendor/package name - SNIFF: 1 # Run code sniffer on your code? 1 or 0 - IMAGE_ICC: 1 # Run icc profile sniffer on your images? 1 or 0 - EPV: 1 # Run EPV (Extension Pre Validator) on your code? 1 or 0 - EXECUTABLE_FILES: 1 # Run check for executable files? 1 or 0 - PHPBB_BRANCH: 3.3.x # The phpBB branch to run tests on + your composer.json file) in the ``with`` section at the bottom of this file. To save and run your workflow, scroll to the bottom of the page and select **Create a new branch for this commit and start a pull request**. Then, to create a pull @@ -1263,26 +858,11 @@ your unit, database and functional tests will be executed. Customising Your Test Workflow ------------------------------ -You'll notice the ``env`` section of the workflow has options where you can enable or -disable basic tests such as the EPV, Code Sniffer, checking any images in your extension -for ICC profiles and checking for executable text files by changing their variables to -either 1 or 0. - -You can also set the version of phpBB you want your extension tested in using the -``PHPBB_BRANCH`` variable. This tutorial is using the current version of phpBB which -is the 3.3.x branch. Older branches of phpBB are not being supported with Github Actions, -but can instead be used with `Travis-CI.com `_ . - -Finally you may also make changes to the jobs. This tutorial's workflow is split up into several -jobs based on the databases being tested: - -* Basic Checks: The ``basic-checks`` job does not do any PHPUnit testing. This is where EPV, Code Sniffer and Image Profile checks run. If you never intend to run these checks you may either delete or comment out the entire ``basic-checks`` job. - -* MySQL Tests: The ``mysql-tests`` job runs PHPUnit tests in various MySQL and MariaDB and PHP combinations. They are all defined in the ``matrix`` section. This workflow only runs in versions of PHP 7 and PHP 8 but you could, for example, add tests for versions of PHP 5. (Note that to include PHP 5 in the test matrix you must change the ubuntu server for that job to ``runs-on: ubuntu-16.04``). You may delete or comment out some of the tests in the matrix if you do not want to test certain versions of PHP or MySQL or MariaDB. - -* PostgreSQL Tests: The ``postgres-tests`` job runs PHPUnit tests in various versions of PostgreSQL. The PHP version is consistent throughout since the mysql-checks job is where we do most of our PHP environment checks. You may add additional checks to this matrix or you may either delete or comment out the entire ``postgres-tests`` job if you do not intend to test PostgreSQL. +Please refer to the `phpBB Extension Test Framework - Read Me `_ +for a complete list of configuration options and examples. -* MSSQL, SQLite: The ``other-tests`` job runs PHPUnit tests in various versions of MSSQL and SQLite3. You may either delete or comment out the MSSQL or SQLite3 checks in the matrix if you do not want to test on either of those databases, or delete or comment out the entire ``other-tests`` job if you do not intend to test any of these databases. +* `Configuration Options `_ +* `Configuration Examples `_ Final Thoughts on Extension Testing ----------------------------------- @@ -1298,9 +878,9 @@ and regressions in your code that must be fixed. Github Actions also provides Build Status badges. They provide you the code in markdown format so you can add the badge to your repository's README so visitors can see -the build status of your extension. For example (Just change ``GITHUB-USERNAME/REPO-NAME`` +the build status of your extension. For example (Just change ``your-org/your-repo`` to your repository): - .. code-block:: text +.. code-block:: markdown - [![Build Status](https://github.com/GITHUB-USERNAME/REPO-NAME/workflows/Tests/badge.svg)](https://github.com/GITHUB-USERNAME/REPO-NAME/actions) + [![Tests](https://github.com/your-org/your-repo/actions/workflows/tests.yml/badge.svg)](https://github.com/your-org/your-repo/actions/workflows/tests.yml)