From 084a0a472ebd37edd5c7aee9ec85a6e1660b0b62 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Tue, 21 Sep 2021 03:26:34 +0200 Subject: [PATCH] README: add information about use with setup-php As of version 2.15.0 of the `shivammathur/setup-php` action for GitHub Actions, the PHPUnit Polyfills can be installed directly from this action using the `tools` key. In that case, both this package as well as PHPUnit will be globally installed via Composer. This commit adds an FAQ section to the readme with a little more information about how this works and how to get things running when installed like that. --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index aa68d5b..d39068b 100644 --- a/README.md +++ b/README.md @@ -690,6 +690,38 @@ Yes, this package can also be used when running tests via a PHPUnit Phar file. In that case, make sure that the `phpunitpolyfills-autoload.php` file is explicitly `require`d in the test bootstrap file. (Not necessary when the Composer `vendor/autoload.php` file is used as, or `require`d in, the test bootstrap.) + +### Q: How do I run my tests when the library is installed via the GitHub Actions `setup-php` action ? + +As of [shivammathur/setup-php](https://github.com/shivammathur/setup-php) version [2.15.0](https://github.com/shivammathur/setup-php/releases/tag/2.15.0), the PHPUnit Polyfills are available as one of the tools which can be installed directly by the Setup-PHP GitHub action. + +```yaml +- name: Setup PHP with tools + uses: shivammathur/setup-php@v2 + with: + php-version: '8.0' + tools: phpunit-polyfills +``` + +The above step will install both the PHPUnit Polyfills, as well as PHPUnit, as Composer global packages. + +After this step has run, you can run PHPUnit, like you would normally, by using `phpunit`. +```yaml +- name: Run tests + run: phpunit +``` + +:point_right: If you rely on Composer for autoloading your project files, you will still need to run `composer autoload --dev` and include the project local `vendor/autoload.php` file as/in your test bootstrap. + +> :mortar_board: Why this works: +> +> Composer will place all files in the global Composer `bin` directory in the system path and the Composer installed PHPUnit version will load the Composer global `autoload.php` file, which will automatically also load the PHPUnit Polyfills. + +Now you may wonder, _"what about if I explicitly request both `phpunit` as well as `phpunit-polyfills` in `tools`?"_ + +In that case, when you run `phpunit`, the PHPUnit PHAR will not know how to locate the PHPUnit Polyfills, so you will need to do some wizardry in your test bootstrap to get things working. + + ### Q: How can I verify the version used of the PHPUnit Polyfills library ? For complex test setups, like when the Polyfills are provided via a test suite dependency, or may already be loaded via an overarching project, it can be useful to be able to check that a version of the package is used which complies with the requirements for your test suite.