From 76b94137b62d420625302e78460c8eb47edd3b74 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 19 Dec 2022 12:59:59 +0100
Subject: [PATCH 01/22] GH Actions: minor simplification

... of the bash `date` command in the earlier pulled cache busting.
---
 .github/workflows/cs.yml   | 4 ++--
 .github/workflows/lint.yml | 4 ++--
 .github/workflows/test.yml | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/cs.yml b/.github/workflows/cs.yml
index bc07b78..43a8bd5 100644
--- a/.github/workflows/cs.yml
+++ b/.github/workflows/cs.yml
@@ -34,8 +34,8 @@ jobs:
       - name: Install Composer dependencies
         uses: "ramsey/composer-install@v2"
         with:
-          # Bust the cache at least once a month - output format: YYYY-MM-DD.
-          custom-cache-suffix: $(date -u -d "-0 month -$(($(date +%d)-1)) days" "+%F")
+          # Bust the cache at least once a month - output format: YYYY-MM.
+          custom-cache-suffix: $(date -u "+%Y-%m")
 
       # Validate the composer.json file.
       # @link https://getcomposer.org/doc/03-cli.md#validate
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 7e3c215..1caae39 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -43,8 +43,8 @@ jobs:
       - name: Install Composer dependencies
         uses: "ramsey/composer-install@v2"
         with:
-          # Bust the cache at least once a month - output format: YYYY-MM-DD.
-          custom-cache-suffix: $(date -u -d "-0 month -$(($(date +%d)-1)) days" "+%F")
+          # Bust the cache at least once a month - output format: YYYY-MM.
+          custom-cache-suffix: $(date -u "+%Y-%m")
 
       - name: "Lint PHP files against parse errors - PHP < 7.0"
         if: ${{ matrix.php < 7.0 }}
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 5908839..e991e9d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -92,8 +92,8 @@ jobs:
       - name: Install Composer dependencies
         uses: "ramsey/composer-install@v2"
         with:
-          # Bust the cache at least once a month - output format: YYYY-MM-DD.
-          custom-cache-suffix: $(date -u -d "-0 month -$(($(date +%d)-1)) days" "+%F")
+          # Bust the cache at least once a month - output format: YYYY-MM.
+          custom-cache-suffix: $(date -u "+%Y-%m")
 
       - name: Run the unit tests
         if: ${{ matrix.phpunit != '^10.0' }}

From f235082e7f5aa443f462f2e0f6ed898aca7e18de Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 19 Dec 2022 13:12:38 +0100
Subject: [PATCH 02/22] GH Actions: improve performance of the CS step

All the repos in the Yoast organisation contain a `<arg name="cache" value="./.cache/phpcs.cache"/>` directive in the PHPCS ruleset.
This directive makes running PHPCS faster by caching the run results in a file and only scanning changed files when running PHPCS again.

However, when there is no cache available, running with the `cache` option enabled will make PHPCS _slower_ as the cache needs to be created and the file read/write actions slow PHPCS down.

In GH Actions, we are not caching the PHPCS `cache` file, which means that there is cache file available and running with `cache` will be slower.

By adding the `--no-cache` option, the `cache` directive in the ruleset is ignored, which should result in a slightly faster runtime for the CS workflow.

Note: the alternative would be to _cache_ the cache file in GH Actions, but aside from the two very frequently changing repos, there's not much point doing that.
---
 .github/workflows/cs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/cs.yml b/.github/workflows/cs.yml
index 43a8bd5..8017bb3 100644
--- a/.github/workflows/cs.yml
+++ b/.github/workflows/cs.yml
@@ -45,7 +45,7 @@ jobs:
       # Check the code-style consistency of the PHP files.
       - name: Check PHP code style
         id: phpcs
-        run: composer check-cs -- --report-full --report-checkstyle=./phpcs-report.xml
+        run: composer check-cs -- --no-cache --report-full --report-checkstyle=./phpcs-report.xml
 
       - name: Show PHPCS results in PR
         if: ${{ always() && steps.phpcs.outcome == 'failure' }}

From c5b1d4709f567158bb009be466f4078fcef3d8fa Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 19 Dec 2022 13:44:10 +0100
Subject: [PATCH 03/22] GH Actions: enable linting and testing against PHP 8.3

While early days for PHP 8.3, as this is a test related package, it needs to be ready early, so better to start running the lint and test workflows against PHP 8.3 already.

Include adding a "low" dependency test run for PHP 8.2.
---
 .github/workflows/lint.yml | 15 +++++++++++++--
 .github/workflows/test.yml | 19 +++++++++++++++++--
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 1caae39..01d05c7 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -20,7 +20,9 @@ jobs:
 
     strategy:
       matrix:
-        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2']
+        php: ['5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3']
+
+    continue-on-error: ${{ matrix.php == '8.3' }}
 
     name: "Lint: PHP ${{ matrix.php }}"
 
@@ -40,9 +42,18 @@ jobs:
 
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-composer-dependencies
-      - name: Install Composer dependencies
+      - name: Install Composer dependencies - normal
+        if: matrix.php != '8.3'
+        uses: "ramsey/composer-install@v2"
+        with:
+          # Bust the cache at least once a month - output format: YYYY-MM.
+          custom-cache-suffix: $(date -u "+%Y-%m")
+
+      - name: Install Composer dependencies - ignore PHP restrictions
+        if: matrix.php == '8.3'
         uses: "ramsey/composer-install@v2"
         with:
+          composer-options: --ignore-platform-req=php+
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")
 
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index e991e9d..4fac066 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -58,12 +58,18 @@ jobs:
           - php: '8.1'
             phpunit: '9.3.0'
             experimental: false
+          - php: '8.2'
+            phpunit: '9.3.0'
+            experimental: false
 
           # Experimental builds.
+          - php: '8.3'
+            phpunit: 'auto'
+            experimental: true
+
           - php: '8.1'
             phpunit: '^10.0'
             experimental: true
-
           - php: '8.2'
             phpunit: '^10.0'
             experimental: true
@@ -89,9 +95,18 @@ jobs:
 
       # Install dependencies and handle caching in one go.
       # @link https://github.com/marketplace/actions/install-composer-dependencies
-      - name: Install Composer dependencies
+      - name: Install Composer dependencies - normal
+        if: matrix.php != '8.3'
+        uses: "ramsey/composer-install@v2"
+        with:
+          # Bust the cache at least once a month - output format: YYYY-MM.
+          custom-cache-suffix: $(date -u "+%Y-%m")
+
+      - name: Install Composer dependencies - ignore PHP restrictions
+        if: matrix.php == '8.3'
         uses: "ramsey/composer-install@v2"
         with:
+          composer-options: --ignore-platform-req=php+
           # Bust the cache at least once a month - output format: YYYY-MM.
           custom-cache-suffix: $(date -u "+%Y-%m")
 

From 2c5638c45af5f52583f371cd1e2a7220c06f0ab6 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 9 Jan 2023 13:16:50 +0100
Subject: [PATCH 04/22] Composer: update YoastCS and dependencies

* YoastCS 2.3.0 has been released. Previous version used was `2.2.1`.
    Ref: https://github.com/Yoast/yoastcs/releases/tag/2.3.0
* Version 1.0.0 of the Composer PHPCS plugin has been released. Previous version used was `0.7.2`.
    Ref: https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases
---
 composer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/composer.json b/composer.json
index 1ce3c03..65d4510 100644
--- a/composer.json
+++ b/composer.json
@@ -27,7 +27,7 @@
         "phpunit/phpunit": "^4.8.36 || ^5.7.21 || ^6.0 || ^7.0 || ^8.0 || ^9.0"
     },
     "require-dev": {
-        "yoast/yoastcs": "^2.2.1"
+        "yoast/yoastcs": "^2.3.0"
     },
     "config": {
         "allow-plugins": {

From b63c01cc9066946100650ba0e87e4bed93f9cf27 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 01:17:20 +0100
Subject: [PATCH 05/22] Tests: make dataproviders `static`

As of PHPUnit 10, data providers are (again) expected to be `static` methods.

This updates the test suite for the polyfills to respect that.
---
 tests/Polyfills/AssertClosedResourceNotResourceTest.php | 2 +-
 tests/Polyfills/AssertStringContainsTest.php            | 2 +-
 tests/TestCases/TestCaseTestTrait.php                   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/Polyfills/AssertClosedResourceNotResourceTest.php b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
index acdfb86..b723bdb 100644
--- a/tests/Polyfills/AssertClosedResourceNotResourceTest.php
+++ b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
@@ -76,7 +76,7 @@ public function testShouldClosedResourceAssertionBeSkipped( $value ) {
 	 *
 	 * @return array
 	 */
-	public function dataNotResource() {
+	public static function dataNotResource() {
 		return [
 			'null'            => [ null ],
 			'false'           => [ false ],
diff --git a/tests/Polyfills/AssertStringContainsTest.php b/tests/Polyfills/AssertStringContainsTest.php
index d31150c..18b31ca 100644
--- a/tests/Polyfills/AssertStringContainsTest.php
+++ b/tests/Polyfills/AssertStringContainsTest.php
@@ -148,7 +148,7 @@ public function testAssertStringNotContainsStringIgnoringCaseEmptyNeedle() {
 	 *
 	 * @return array
 	 */
-	public function dataHaystacks() {
+	public static function dataHaystacks() {
 		return [
 			'foobar as haystack' => [ 'foobar' ],
 			'empty haystack'     => [ '' ],
diff --git a/tests/TestCases/TestCaseTestTrait.php b/tests/TestCases/TestCaseTestTrait.php
index a4a80f0..40c713c 100644
--- a/tests/TestCases/TestCaseTestTrait.php
+++ b/tests/TestCases/TestCaseTestTrait.php
@@ -16,7 +16,7 @@ trait TestCaseTestTrait {
 	 *
 	 * @return array[]
 	 */
-	public function dataHaveFixtureMethodsBeenTriggered() {
+	public static function dataHaveFixtureMethodsBeenTriggered() {
 		return [
 			[ 1, 1, 0, 1, 0 ],
 			[ 1, 2, 1, 2, 1 ],

From 1d3fa5257b3b01dcdb4005ae9c041224a8be4da6 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 01:38:46 +0100
Subject: [PATCH 06/22] AssertClosedResourceTestCase: update exception message
 expectation

... for a minor change in the exception message thrown by PHPUnit 10.0.
---
 tests/Polyfills/AssertClosedResourceTestCase.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/Polyfills/AssertClosedResourceTestCase.php b/tests/Polyfills/AssertClosedResourceTestCase.php
index 3c6d4e2..8b1eba6 100644
--- a/tests/Polyfills/AssertClosedResourceTestCase.php
+++ b/tests/Polyfills/AssertClosedResourceTestCase.php
@@ -24,7 +24,7 @@ abstract class AssertClosedResourceTestCase extends TestCase {
 	 * @return void
 	 */
 	public function isClosedResourceExpectExceptionOnOpenResource( $actual ) {
-		$pattern   = '`^Failed asserting that .+? is of type "resource \(closed\)"`';
+		$pattern   = '`^Failed asserting that .+? is of type ["]?resource \(closed\)["]?`';
 		$exception = 'PHPUnit\Framework\AssertionFailedError';
 		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
 			// PHPUnit < 6.
@@ -49,7 +49,7 @@ public function isNotClosedResourceExpectExceptionOnClosedResource( $actual ) {
 		 * PHPUnit itself will report closed resources as `NULL` prior to Exporter 3.0.4/4.1.4.
 		 * See: https://github.com/sebastianbergmann/exporter/pull/37
 		 */
-		$pattern   = '`^Failed asserting that (resource \(closed\)|NULL) is not of type "resource \(closed\)"`';
+		$pattern   = '`^Failed asserting that (resource \(closed\)|NULL) is not of type ["]?resource \(closed\)["]?`';
 		$exception = 'PHPUnit\Framework\AssertionFailedError';
 		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
 			// PHPUnit < 6.

From 86657f3bd37765c3950810e465d306d7c8e1381d Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 01:41:47 +0100
Subject: [PATCH 07/22] AssertClosedResourceNotResourceTest: update exception
 message expectation

... for a minor change in the exception message thrown by PHPUnit 10.0.
---
 tests/Polyfills/AssertClosedResourceNotResourceTest.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Polyfills/AssertClosedResourceNotResourceTest.php b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
index b723bdb..912b60f 100644
--- a/tests/Polyfills/AssertClosedResourceNotResourceTest.php
+++ b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
@@ -31,7 +31,7 @@ final class AssertClosedResourceNotResourceTest extends TestCase {
 	 * @return void
 	 */
 	public function testAssertIsClosedResource( $value ) {
-		$pattern   = '`^Failed asserting that .+? is of type "resource \(closed\)"`s';
+		$pattern   = '`^Failed asserting that .+? is of type ["]?resource \(closed\)["]?`s';
 		$exception = 'PHPUnit\Framework\AssertionFailedError';
 		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
 			// PHPUnit < 6.

From 23397bb2cbb7d9ab4bd90940e1a2da401ad7cb8e Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 6 Jun 2021 06:53:33 +0200
Subject: [PATCH 08/22] Tests: minor update for release of PHPUnit 10.0.0

Update some `@requires` tags now PHPUnit 10.0 has been released.
---
 tests/Polyfills/AssertFileDirectoryTest.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/Polyfills/AssertFileDirectoryTest.php b/tests/Polyfills/AssertFileDirectoryTest.php
index 676c1b7..19cf249 100644
--- a/tests/Polyfills/AssertFileDirectoryTest.php
+++ b/tests/Polyfills/AssertFileDirectoryTest.php
@@ -79,7 +79,7 @@ public function testAssertNotIsReadable() {
 	 * This exception was thrown until PHP 7.0.0. Since PHP 7.0.0, a PHP native TypeError will
 	 * be thrown based on the type declaration.
 	 *
-	 * @requires PHPUnit < 9.99.99
+	 * @requires PHPUnit < 10.0.0
 	 */
 	public function testAssertNotIsReadableException() {
 		try {
@@ -163,7 +163,7 @@ public function testAssertNotIsWritable() {
 	 * This exception was thrown until PHP 7.0.0. Since PHP 7.0.0, a PHP native TypeError will
 	 * be thrown based on the type declaration.
 	 *
-	 * @requires PHPUnit < 9.99.99
+	 * @requires PHPUnit < 10.0.0
 	 */
 	public function testAssertNotIsWritableException() {
 		try {
@@ -247,7 +247,7 @@ public function testAssertDirectoryNotExists() {
 	 * This exception was thrown until PHP 7.0.0. Since PHP 7.0.0, a PHP native TypeError will
 	 * be thrown based on the type declaration.
 	 *
-	 * @requires PHPUnit < 9.99.99
+	 * @requires PHPUnit < 10.0.0
 	 */
 	public function testAssertDirectoryNotExistsException() {
 		try {

From 40162735c27c5d8ba554a37e59b9358baf96c0cb Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 3 Jan 2022 05:21:20 +0100
Subject: [PATCH 09/22] README: enhance the TOC

... and correct it.
---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1f68c66..3180f5c 100644
--- a/README.md
+++ b/README.md
@@ -12,10 +12,12 @@ PHPUnit Polyfills
 Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit cross-version compatible tests.
 
 * [Requirements](#requirements)
-    - [Autoloading](#autoloading)
 * [Installation](#installation)
+    - [Autoloading](#autoloading)
 * [Why use the PHPUnit Polyfills?](#why-use-the-phpunit-polyfills)
 * [Using this library](#using-this-library)
+    - [Supported ways of calling the assertions](#supported-ways-of-calling-the-assertions)
+    - [Use with PHPUnit < 5.7.0](#use-with-phpunit--570)
 * [Features](#features)
     - [Polyfill traits](#polyfill-traits)
     - [Helper traits](#helper-traits)

From 243f2c0887176867624ca404b7b7b33fca12204d Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 19:59:03 +0100
Subject: [PATCH 10/22] GH Actions: add new check for consistency in markdown
 files

This new check uses the NPM MarkdownLint package via the NPM MarkdownLint-CLI2 package.

It executes a loose check for consistency and some common errors.
Some of the more annoying rules/rules which could impact display of markdown files on GitHub have been disabled.

All necessary configuration is contained in the `.markdownlint-cli2.yaml` file.

To run locally, install via:
```bash
npm install -g markdownlint-cli2
```
... and then run via:
```bash
markdownlint-cli2
```

Includes a problem matcher which _should_ allow for displaying the results inline in GitHub PR code review view.

Includes adding `node_modules` to the `.gitignore` in case anyone would install these tools locally (to prevent them committing them).

Refs:
* https://github.com/DavidAnson/markdownlint
* https://github.com/DavidAnson/markdownlint-cli2
---
 .gitattributes                 |   1 +
 .github/workflows/markdown.yml |  48 +++++++++++++++
 .gitignore                     |   1 +
 .markdownlint-cli2.yaml        | 107 +++++++++++++++++++++++++++++++++
 4 files changed, 157 insertions(+)
 create mode 100644 .github/workflows/markdown.yml
 create mode 100644 .markdownlint-cli2.yaml

diff --git a/.gitattributes b/.gitattributes
index 074a6f2..f7895de 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -9,6 +9,7 @@
 /.gitignore export-ignore
 /.cache/ export-ignore
 /.github/ export-ignore
+/.markdownlint-cli2.yaml export-ignore
 /.phpcs.xml.dist export-ignore
 /phpunit.xml.dist export-ignore
 /tests/ export-ignore
diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
new file mode 100644
index 0000000..9c0ab98
--- /dev/null
+++ b/.github/workflows/markdown.yml
@@ -0,0 +1,48 @@
+name: MarkDown
+
+on:
+  # Run on all pushes and on all pull requests.
+  push:
+  pull_request:
+  # Also run this workflow every Monday at 6:00.
+  schedule:
+    - cron: '0 6 * * 1'
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+# Cancels all previous workflow runs for the same branch that have not yet completed.
+concurrency:
+  # The concurrency group contains the workflow name and the branch name.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdownlint:
+    name: 'Lint Markdown'
+    runs-on: ubuntu-latest
+
+    # Don't run the cronjob in this workflow on forks.
+    if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository_owner == 'Yoast')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      # This action also handles the caching of the dependencies.
+      # https://github.com/actions/setup-node
+      - name: Set up node and enable caching of dependencies
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      # @link https://github.com/DavidAnson/markdownlint-cli2
+      # @link https://github.com/DavidAnson/markdownlint
+      - name: Install Markdownlint CLI2
+        run: npm install -g markdownlint-cli2
+
+      # @link https://github.com/marketplace/actions/problem-matcher-for-markdownlint-cli
+      - name: Enable showing issue in PRs
+        uses: xt0rted/markdownlint-problem-matcher@v1
+
+      - name: Check markdown with CLI2
+        run: markdownlint-cli2
diff --git a/.gitignore b/.gitignore
index be62b84..179ad62 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 /composer.lock
+node_modules/
 vendor/
 /.phpcs.xml
 /phpcs.xml
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
new file mode 100644
index 0000000..0255a55
--- /dev/null
+++ b/.markdownlint-cli2.yaml
@@ -0,0 +1,107 @@
+#
+# Configuration file for MarkdownLint-CLI2.
+#
+# Example file with all options:
+# https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml
+#
+
+# Do not fix any fixable errors.
+fix: false
+
+# Define glob expressions to use (only valid at root).
+globs:
+  - "**/*.md"
+  - ".github/**/*.md"
+
+# Define glob expressions to ignore.
+ignores:
+  - "node_modules/"
+  - "vendor/"
+
+# Disable inline config comments.
+noInlineConfig: true
+
+# Disable progress on stdout (only valid at root).
+noProgress: false
+
+# Adjust the configuration for some built-in rules.
+# For full information on the options and defaults, see:
+# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+config:
+  ######################
+  # Disable a few rules.
+  ######################
+  # MD003/heading-style/header-style - Heading style.
+  MD003: false
+  # MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines.
+  MD031: false
+  # MD032/blanks-around-lists - Lists should be surrounded by blank lines.
+  MD032: false
+
+  ##############################
+  # Customize a few other rules.
+  ##############################
+  # MD004/ul-style - Unordered list style.
+  MD004:
+    # List style - each level has a different, but consistent symbol.
+    style: "sublist"
+
+  # MD007/ul-indent - Unordered list indentation.
+  MD007:
+    indent: 4
+    # Whether to indent the first level of the list.
+    start_indented: false
+
+  # MD012/no-multiple-blanks - Multiple consecutive blank lines.
+  MD012:
+    maximum: 2
+
+  # MD013/line-length - Line length.
+  MD013:
+    # Number of characters. No need for being too fussy.
+    line_length: 1000
+    # Number of characters for headings.
+    heading_line_length: 105
+    # Number of characters for code blocks.
+    code_block_line_length: 100
+    # Stern length checking (applies to tables, code blocks etc which have their own max line length).
+    stern: true
+
+  # MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
+  MD022:
+    # Blank lines below heading
+    lines_below: false
+
+  # MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content.
+  MD024:
+    # Only check sibling headings.
+    siblings_only: true
+
+  # MD033/no-inline-html - Inline HTML.
+  MD033:
+    # Allowed elements.
+    allowed_elements:
+      - br
+
+  # MD044/proper-names - Proper names should have the correct capitalization.
+  MD044:
+    # List of proper names.
+    names: ["PHPUnit"]
+    # Include code blocks.
+    code_blocks: false
+
+  # MD046/code-block-style - Code block style
+  MD046:
+    style: "fenced"
+
+  # MD048/code-fence-style - Code fence style
+  MD048:
+    style: "backtick"
+
+  # MD049/emphasis-style - Emphasis style should be consistent
+  MD049:
+    style: "underscore"
+
+  # MD050/strong-style - Strong style should be consistent
+  MD050:
+    style: "asterisk"

From 092d150ae93b6b38bfaa13fade25d74358be7a63 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 19:59:35 +0100
Subject: [PATCH 11/22] Docs: minimal changes to pass the markdownlint check

---
 .github/RELEASE-CHECKLIST.md |  6 +++---
 README.md                    | 10 ++++++----
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/.github/RELEASE-CHECKLIST.md b/.github/RELEASE-CHECKLIST.md
index c0d7fca..cfc5ca0 100644
--- a/.github/RELEASE-CHECKLIST.md
+++ b/.github/RELEASE-CHECKLIST.md
@@ -3,12 +3,12 @@ Template to use for release PRs from `develop` to `main`
 
 Title: Release version x.x.x
 
-### Functional:
+## Functional
 - [ ] Confirm that the most recent PHPUnit changelogs have been checked and that the library is still feature complete for those versions supported within the PHPUnit version constraints.
 - [ ] Update the `VERSION` constant in the `phpunitpolyfills-autoload.php` file.
 - [ ] Composer: check if any dependencies/version constraints need updating.
 
-### Release:
+## Release
 - [ ] Add changelog for the release - PR #xxx
     Verify that a release link at the bottom of the `CHANGELOG.md` file has been added.
 - [ ] Merge this PR.
@@ -20,7 +20,7 @@ Title: Release version x.x.x
 - [ ] Open a new milestone for the next release.
 - [ ] If any open PRs/issues which were milestoned for the release did not make it into the release, update their milestone.
 
-### Announce:
+## Announce
 - [ ] Tweet about the release.
 
 
diff --git a/README.md b/README.md
index 3180f5c..7fc24c7 100644
--- a/README.md
+++ b/README.md
@@ -701,7 +701,7 @@ In that case, make sure that the `phpunitpolyfills-autoload.php` file is explici
 
 ### 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.
+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 runner.
 
 ```yaml
 - name: Setup PHP with tools
@@ -746,12 +746,14 @@ $versionRequirement = '1.0.1';
 if ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
     || version_compare( \Yoast\PHPUnitPolyfills\Autoload::VERSION, $versionRequirement, '<' )
 ) {
-    echo 'Error: Version mismatch detected for the PHPUnit Polyfills. Please ensure that PHPUnit Polyfills ',
-        $versionRequirement, ' or higher is loaded.', PHP_EOL;
+    echo 'Error: Version mismatch detected for the PHPUnit Polyfills.',
+        ' Please ensure that PHPUnit Polyfills ', $versionRequirement,
+        ' or higher is loaded.', PHP_EOL;
     exit(1);
 } else {
     echo 'Error: Please run `composer update -W` before running the tests.' . PHP_EOL;
-    echo 'You can still use a PHPUnit phar to run them, but the dependencies do need to be installed.', PHP_EOL;
+    echo 'You can still use a PHPUnit phar to run them,',
+        ' but the dependencies do need to be installed.', PHP_EOL;
     exit(1);
 }
 ```

From 5b01ae70b8cec75e6970ef29f339af34243c9575 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 20:02:45 +0100
Subject: [PATCH 12/22] GH Actions: add new check with additional QA for
 markdown files

While MarkdownLint is absolutely great for finding formatting issues, Remark offers some additional "rules" which are useful, such as checking that links and link definitions match up, verifying all used links work and some additional formatting checks which markdownlint just doesn't offer.

An extensive effort has been made to prevent duplication of messages between the Markdownlint and the Remark check. This includes ensuring there are no conflicting rules.

The rule configuration is contained in the `.remarkrc` file.

Files/directories to be ignored can be listed in the `.remarkignore` file which supports glob syntax, like `.gitignore`.
Note: `.`-prefixed files and directories are excluded by default. To include those in the scan, they have to be passed explicitly on the command-line.

To run locally, follow the same steps as per the GitHub actions workflow.

Note: the workflow contains a double-run of remark-lint to allow viewing the results both in a human readable way in the actions transscripts, as well as getting annotations for found issue in PRs.

Refs:
* https://github.com/remarkjs/remark/tree/main/packages/remark-cli
* https://github.com/remarkjs/remark-lint
* https://github.com/remarkjs/remark-gfm
* https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent
* https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended
* https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide

Additional (external) plugins included:
* https://github.com/vhf/remark-lint-heading-whitespace
* https://github.com/wemake-services/remark-lint-list-item-punctuation
* https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-match-punctuation
* https://github.com/olizilla/remark-lint-no-hr-after-heading
* https://github.com/wemake-services/remark-lint-are-links-valid
* https://github.com/remarkjs/remark-validate-links
---
 .gitattributes                 |  2 ++
 .github/workflows/markdown.yml | 64 ++++++++++++++++++++++++++++++++++
 .remarkignore                  |  5 +++
 .remarkrc                      | 35 +++++++++++++++++++
 4 files changed, 106 insertions(+)
 create mode 100644 .remarkignore
 create mode 100644 .remarkrc

diff --git a/.gitattributes b/.gitattributes
index f7895de..67ccd8e 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -11,6 +11,8 @@
 /.github/ export-ignore
 /.markdownlint-cli2.yaml export-ignore
 /.phpcs.xml.dist export-ignore
+/.remarkignore export-ignore
+/.remarkrc export-ignore
 /phpunit.xml.dist export-ignore
 /tests/ export-ignore
 
diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
index 9c0ab98..5f0fcd5 100644
--- a/.github/workflows/markdown.yml
+++ b/.github/workflows/markdown.yml
@@ -46,3 +46,67 @@ jobs:
 
       - name: Check markdown with CLI2
         run: markdownlint-cli2
+
+  remark:
+    name: 'QA Markdown'
+    runs-on: ubuntu-latest
+
+    # Don't run the cronjob in this workflow on forks.
+    if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository_owner == 'Yoast')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up node and enable caching of dependencies
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      # To make the command available on CLI, it needs to be installed globally.
+      - name: Install Remark CLI globally
+        run: npm install --global remark-cli --foreground-scripts true --fund false
+
+      # To allow for creating a custom config which references rules which are included
+      # in the presets, without having to install all rules individually, a local install
+      # works best (and installing the presets in the first place, of course).
+      #
+      # Note: the first group of packages are all part of the mono "Remark lint" repo.
+      # The second group of packages (heading-whitespace and down) are additional
+      # "external" rules/plugins.
+      - name: Install Remark rules locally
+        run: >
+          npm install --foreground-scripts true --fund false
+          remark-lint
+          remark-gfm
+          remark-preset-lint-consistent
+          remark-preset-lint-recommended
+          remark-preset-lint-markdown-style-guide
+          remark-lint-checkbox-content-indent
+          remark-lint-linebreak-style
+          remark-lint-no-empty-url
+          remark-lint-no-heading-like-paragraph
+          remark-lint-no-reference-like-url
+          remark-lint-no-unneeded-full-reference-image
+          remark-lint-no-unneeded-full-reference-link
+          remark-lint-strikethrough-marker
+          remark-lint-heading-whitespace
+          remark-lint-list-item-punctuation
+          remark-lint-match-punctuation
+          remark-lint-no-hr-after-heading
+          remark-lint-are-links-valid-alive
+          remark-lint-are-links-valid-duplicate
+          remark-validate-links
+
+      - name: Run Remark-lint
+        run: remark . --frail
+
+      # @link https://github.com/reviewdog/action-remark-lint
+      - name: Show Remark-lint annotations in PR
+        if: ${{ failure() && github.event_name == 'pull_request' }}
+        uses: reviewdog/action-remark-lint@v5
+        with:
+          fail_on_error: true
+          install_deps: false
+          level: info
+          reporter: github-pr-check
diff --git a/.remarkignore b/.remarkignore
new file mode 100644
index 0000000..6718a0b
--- /dev/null
+++ b/.remarkignore
@@ -0,0 +1,5 @@
+# Ignore rules for Remark.
+# Docs: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md
+
+/node_modules/
+/vendor/
diff --git a/.remarkrc b/.remarkrc
new file mode 100644
index 0000000..e54bb8b
--- /dev/null
+++ b/.remarkrc
@@ -0,0 +1,35 @@
+{
+  "plugins": [
+    "remark-gfm",
+    ["remark-lint-checkbox-character-style", "consistent"],
+    ["remark-lint-checkbox-content-indent", "consistent"],
+    "remark-lint-definition-spacing",
+    "remark-lint-file-extension",
+    ["remark-lint-linebreak-style", "unix"],
+    ["remark-lint-link-title-style", "\""],
+    ["remark-lint-ordered-list-marker-style", "."],
+    "remark-lint-no-duplicate-definitions",
+    "remark-lint-no-empty-url",
+    "remark-lint-no-file-name-consecutive-dashes",
+    "remark-lint-no-file-name-irregular-characters",
+    "remark-lint-no-file-name-outer-dashes",
+    "remark-lint-no-heading-like-paragraph",
+    "remark-lint-no-literal-urls",
+    "remark-lint-no-reference-like-url",
+    "remark-lint-no-shortcut-reference-image",
+    "remark-lint-no-table-indentation",
+    "remark-lint-no-undefined-references",
+    "remark-lint-no-unneeded-full-reference-image",
+    "remark-lint-no-unneeded-full-reference-link",
+    "remark-lint-no-unused-definitions",
+    ["remark-lint-strikethrough-marker", "~~"],
+    ["remark-lint-table-cell-padding", "consistent"],
+    "remark-lint-heading-whitespace",
+    "remark-lint-list-item-punctuation",
+    "remark-lint-match-punctuation",
+    "remark-lint-no-hr-after-heading",
+    "remark-lint-are-links-valid-alive",
+    "remark-lint-are-links-valid-duplicate",
+    "remark-validate-links"
+  ]
+}

From b6d80f2527b1555fe15b3995f8af3f5822931171 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 20:12:25 +0100
Subject: [PATCH 13/22] Docs: minimal changes to pass the remark check

---
 README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7fc24c7..7dc2c66 100644
--- a/README.md
+++ b/README.md
@@ -617,7 +617,7 @@ class MyTest extends XTestCase {
 ### TestListener
 
 The method signatures in the PHPUnit `TestListener` interface have changed a number of times across versions.
-Additionally, the use of the TestListener principle has been deprecated in PHPUnit 7 in favour of using the [TestRunner hook interfaces](https://phpunit.readthedocs.io/en/9.3/extending-phpunit.html#extending-the-testrunner).
+Additionally, the use of the TestListener principle has been deprecated in PHPUnit 7 in favour of using the [TestRunner hook interfaces](https://docs.phpunit.de/en/7.5/extending-phpunit.html#extending-the-testrunner).
 
 > Note: while deprecated in PHPUnit 7, the TestListener interface has not yet been removed and is still supported in PHPUnit 9.x.
 
@@ -687,9 +687,11 @@ For frequently used, removed PHPUnit functionality, "helpers" may be provided. T
 
 | PHPUnit | Removed               | Issue     | Remarks                |
 |---------|-----------------------|-----------|------------------------|
-| 9.0.0   | `assertArraySubset()` | [#1](https://github.com/Yoast/PHPUnit-Polyfills/issues/1) | The [`dms/phpunit-arraysubset-asserts`](https://packagist.org/packages/dms/phpunit-arraysubset-asserts) package polyfills this functionality.<br/>As of [version 0.3.0](https://github.com/rdohms/phpunit-arraysubset-asserts/releases/tag/v0.3.0) this package can be installed in combination with PHP 5.4 - current and PHPUnit 4.8.36/5.7.21 - current.<br/>Alternatively, tests can be refactored using the patterns outlined in [issue #1](https://github.com/Yoast/PHPUnit-Polyfills/issues/1).
-| 9.0.0   | `assertAttribute*()`  | [#2](https://github.com/Yoast/PHPUnit-Polyfills/issues/2) | Refactor the tests to not directly test private/protected properties.<br/>As an interim solution, the [`Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper`](#yoastphpunitpolyfillshelpersassertattributehelper) trait is available.
+| 9.0.0   | `assertArraySubset()` | [#1][issue #1] | The [`dms/phpunit-arraysubset-asserts`](https://packagist.org/packages/dms/phpunit-arraysubset-asserts) package polyfills this functionality.<br/>As of [version 0.3.0](https://github.com/rdohms/phpunit-arraysubset-asserts/releases/tag/v0.3.0) this package can be installed in combination with PHP 5.4 - current and PHPUnit 4.8.36/5.7.21 - current.<br/>Alternatively, tests can be refactored using the patterns outlined in [issue #1]. |
+| 9.0.0   | `assertAttribute*()`  | [#2][issue #2] | Refactor the tests to not directly test private/protected properties.<br/>As an interim solution, the [`Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper`](#yoastphpunitpolyfillshelpersassertattributehelper) trait is available. |
 
+[issue #1]: https://github.com/Yoast/PHPUnit-Polyfills/issues/1
+[issue #2]: https://github.com/Yoast/PHPUnit-Polyfills/issues/2
 
 ### Q: Can this library be used when the tests are being run via a PHPUnit Phar file ?
 
@@ -768,4 +770,4 @@ If you are unsure whether the changes you are proposing would be welcome, please
 
 License
 -------
-This code is released under the [BSD-3-Clause License](https://opensource.org/licenses/BSD-3-Clause).
+This code is released under the [BSD-3-Clause License](LICENSE).

From f59360183356f905516785ae6e6b2f7bb2b8e29d Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sat, 11 Mar 2023 08:05:49 +0100
Subject: [PATCH 14/22] README: update links to PHPUnit docs

As PHPUnit 10.0 has been released, the `main` branch of the PHPUnit docs now points to the PHPUnit 10.0 documentation, while the last release of the Polyfills supports PHPUnit 4.x - 9.x.

This commit updates the links in the README to point explicitly to the PHPUnit 9.6 documentation.

PHPUnit 10.0 support will be handled in a new major of the Polyfills and the links should be updated (again) to point to the PHPUnit 10.0 documentation in the branch containing that major.
---
 README.md | 168 +++++++++++++++++++++++++++---------------------------
 1 file changed, 84 insertions(+), 84 deletions(-)

diff --git a/README.md b/README.md
index 7dc2c66..c527cf4 100644
--- a/README.md
+++ b/README.md
@@ -132,7 +132,7 @@ The polyfills in this library support the first two ways of calling the assertio
 
 For the polyfills to work, a test class is **required** to be a (grand-)child of the PHPUnit native `TestCase` class.
 
-[four ways of calling assertions]: https://phpunit.readthedocs.io/en/main/assertions.html#static-vs-non-static-usage-of-assertion-methods
+[four ways of calling assertions]: https://docs.phpunit.de/en/9.6/assertions.html#static-vs-non-static-usage-of-assertion-methods
 
 ### Use with PHPUnit < 5.7.0
 
@@ -188,9 +188,9 @@ Polyfills the following methods:
 
 These methods were introduced in PHPUnit 5.0.0.
 
-[`Assert::assertFinite()`]:   https://phpunit.readthedocs.io/en/main/assertions.html#assertinfinite
-[`Assert::assertInfinite()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertinfinite
-[`Assert::assertNan()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertnan
+[`Assert::assertFinite()`]:   https://docs.phpunit.de/en/9.6/assertions.html#assertinfinite
+[`Assert::assertInfinite()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertinfinite
+[`Assert::assertNan()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertnan
 
 #### PHPUnit < 5.2.0: `Yoast\PHPUnitPolyfills\Polyfills\ExpectException`
 
@@ -203,10 +203,10 @@ Polyfills the following methods:
 These methods were introduced in PHPUnit 5.2.0 as alternatives to the `Testcase::setExpectedException()` method which was deprecated in PHPUnit 5.2.0 and the `Testcase::setExpectedExceptionRegExp()` method which was deprecated in 5.6.0.
 Both these methods were removed in PHPUnit 6.0.0.
 
-[`TestCase::expectException()`]:              https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-exceptions
-[`TestCase::expectExceptionMessage()`]:       https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-exceptions
-[`TestCase::expectExceptionCode()`]:          https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-exceptions
-[`TestCase::expectExceptionMessageRegExp()`]: https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-exceptions
+[`TestCase::expectException()`]:              https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-exceptions
+[`TestCase::expectExceptionMessage()`]:       https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-exceptions
+[`TestCase::expectExceptionCode()`]:          https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-exceptions
+[`TestCase::expectExceptionMessageRegExp()`]: https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-exceptions
 
 #### PHPUnit < 5.6.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertFileDirectory`
 
@@ -223,20 +223,20 @@ Polyfills the following methods:
 
 These methods were introduced in PHPUnit 5.6.0.
 
-[`Assert::assertIsReadable()`]:             https://phpunit.readthedocs.io/en/main/assertions.html#assertisreadable
-[`Assert::assertNotIsReadable()`]:          https://phpunit.readthedocs.io/en/main/assertions.html#assertisreadable
-[`Assert::assertIsWritable()`]:             https://phpunit.readthedocs.io/en/main/assertions.html#assertiswritable
-[`Assert::assertNotIsWritable()`]:          https://phpunit.readthedocs.io/en/main/assertions.html#assertiswritable
-[`Assert::assertDirectoryExists()`]:        https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryexists
-[`Assert::assertDirectoryNotExists()`]:     https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryexists
-[`Assert::assertDirectoryIsReadable()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryisreadable
-[`Assert::assertDirectoryNotIsReadable()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryisreadable
-[`Assert::assertDirectoryIsWritable()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryiswritable
-[`Assert::assertDirectoryNotIsWritable()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryiswritable
-[`Assert::assertFileIsReadable()`]:         https://phpunit.readthedocs.io/en/main/assertions.html#assertfileisreadable
-[`Assert::assertFileNotIsReadable()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertfileisreadable
-[`Assert::assertFileIsWritable()`]:         https://phpunit.readthedocs.io/en/main/assertions.html#assertfileiswritable
-[`Assert::assertFileNotIsWritable()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertfileiswritable
+[`Assert::assertIsReadable()`]:             https://docs.phpunit.de/en/9.6/assertions.html#assertisreadable
+[`Assert::assertNotIsReadable()`]:          https://docs.phpunit.de/en/9.6/assertions.html#assertisreadable
+[`Assert::assertIsWritable()`]:             https://docs.phpunit.de/en/9.6/assertions.html#assertiswritable
+[`Assert::assertNotIsWritable()`]:          https://docs.phpunit.de/en/9.6/assertions.html#assertiswritable
+[`Assert::assertDirectoryExists()`]:        https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryexists
+[`Assert::assertDirectoryNotExists()`]:     https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryexists
+[`Assert::assertDirectoryIsReadable()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryisreadable
+[`Assert::assertDirectoryNotIsReadable()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryisreadable
+[`Assert::assertDirectoryIsWritable()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryiswritable
+[`Assert::assertDirectoryNotIsWritable()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryiswritable
+[`Assert::assertFileIsReadable()`]:         https://docs.phpunit.de/en/9.6/assertions.html#assertfileisreadable
+[`Assert::assertFileNotIsReadable()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertfileisreadable
+[`Assert::assertFileIsWritable()`]:         https://docs.phpunit.de/en/9.6/assertions.html#assertfileiswritable
+[`Assert::assertFileNotIsWritable()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertfileiswritable
 
 #### PHPUnit < 6.4.0: `Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionObject`
 
@@ -244,7 +244,7 @@ Polyfills the [`TestCase::expectExceptionObject()`] method to test all aspects o
 
 This method was introduced in PHPUnit 6.4.0.
 
-[`TestCase::expectExceptionObject()`]: https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-exceptions
+[`TestCase::expectExceptionObject()`]: https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-exceptions
 
 #### PHPUnit < 7.5.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertIsType`
 
@@ -262,28 +262,28 @@ Polyfills the following methods:
 
 These methods were introduced in PHPUnit 7.5.0 as alternatives to the `Assert::assertInternalType()` and `Assert::assertNotInternalType()` methods, which were soft deprecated in PHPUnit 7.5.0, hard deprecated (warning) in PHPUnit 8.0.0 and removed in PHPUnit 9.0.0.
 
-[`Assert::assertIsArray()`]:       https://phpunit.readthedocs.io/en/main/assertions.html#assertisarray
-[`Assert::assertIsNotArray()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertisarray
-[`Assert::assertIsBool()`]:        https://phpunit.readthedocs.io/en/main/assertions.html#assertisbool
-[`Assert::assertIsNotBool()`]:     https://phpunit.readthedocs.io/en/main/assertions.html#assertisbool
-[`Assert::assertIsFloat()`]:       https://phpunit.readthedocs.io/en/main/assertions.html#assertisfloat
-[`Assert::assertIsNotFloat()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertisfloat
-[`Assert::assertIsInt()`]:         https://phpunit.readthedocs.io/en/main/assertions.html#assertisint
-[`Assert::assertIsNotInt()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertisint
-[`Assert::assertIsNumeric()`]:     https://phpunit.readthedocs.io/en/main/assertions.html#assertisnumeric
-[`Assert::assertIsNotNumeric()`]:  https://phpunit.readthedocs.io/en/main/assertions.html#assertisnumeric
-[`Assert::assertIsObject()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertisobject
-[`Assert::assertIsNotObject()`]:   https://phpunit.readthedocs.io/en/main/assertions.html#assertisobject
-[`Assert::assertIsResource()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertisresource
-[`Assert::assertIsNotResource()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertisresource
-[`Assert::assertIsString()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertisstring
-[`Assert::assertIsNotString()`]:   https://phpunit.readthedocs.io/en/main/assertions.html#assertisstring
-[`Assert::assertIsScalar()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertisscalar
-[`Assert::assertIsNotScalar()`]:   https://phpunit.readthedocs.io/en/main/assertions.html#assertisscalar
-[`Assert::assertIsCallable()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertiscallable
-[`Assert::assertIsNotCallable()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertiscallable
-[`Assert::assertIsIterable()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertisiterable
-[`Assert::assertIsNotIterable()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertisiterable
+[`Assert::assertIsArray()`]:       https://docs.phpunit.de/en/9.6/assertions.html#assertisarray
+[`Assert::assertIsNotArray()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertisarray
+[`Assert::assertIsBool()`]:        https://docs.phpunit.de/en/9.6/assertions.html#assertisbool
+[`Assert::assertIsNotBool()`]:     https://docs.phpunit.de/en/9.6/assertions.html#assertisbool
+[`Assert::assertIsFloat()`]:       https://docs.phpunit.de/en/9.6/assertions.html#assertisfloat
+[`Assert::assertIsNotFloat()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertisfloat
+[`Assert::assertIsInt()`]:         https://docs.phpunit.de/en/9.6/assertions.html#assertisint
+[`Assert::assertIsNotInt()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertisint
+[`Assert::assertIsNumeric()`]:     https://docs.phpunit.de/en/9.6/assertions.html#assertisnumeric
+[`Assert::assertIsNotNumeric()`]:  https://docs.phpunit.de/en/9.6/assertions.html#assertisnumeric
+[`Assert::assertIsObject()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertisobject
+[`Assert::assertIsNotObject()`]:   https://docs.phpunit.de/en/9.6/assertions.html#assertisobject
+[`Assert::assertIsResource()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertisresource
+[`Assert::assertIsNotResource()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertisresource
+[`Assert::assertIsString()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertisstring
+[`Assert::assertIsNotString()`]:   https://docs.phpunit.de/en/9.6/assertions.html#assertisstring
+[`Assert::assertIsScalar()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertisscalar
+[`Assert::assertIsNotScalar()`]:   https://docs.phpunit.de/en/9.6/assertions.html#assertisscalar
+[`Assert::assertIsCallable()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertiscallable
+[`Assert::assertIsNotCallable()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertiscallable
+[`Assert::assertIsIterable()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertisiterable
+[`Assert::assertIsNotIterable()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertisiterable
 
 #### PHPUnit < 7.5.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains`
 
@@ -295,10 +295,10 @@ Polyfills the following methods:
 
 These methods were introduced in PHPUnit 7.5.0 as alternatives to using `Assert::assertContains()` and `Assert::assertNotContains()` with string haystacks. Passing string haystacks to these methods was soft deprecated in PHPUnit 7.5.0, hard deprecated (warning) in PHPUnit 8.0.0 and removed in PHPUnit 9.0.0.
 
-[`Assert::assertStringContainsString()`]:                https://phpunit.readthedocs.io/en/main/assertions.html#assertstringcontainsstring
-[`Assert::assertStringNotContainsString()`]:             https://phpunit.readthedocs.io/en/main/assertions.html#assertstringcontainsstring
-[`Assert::assertStringContainsStringIgnoringCase()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertstringcontainsstringignoringcase
-[`Assert::assertStringNotContainsStringIgnoringCase()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertstringcontainsstringignoringcase
+[`Assert::assertStringContainsString()`]:                https://docs.phpunit.de/en/9.6/assertions.html#assertstringcontainsstring
+[`Assert::assertStringNotContainsString()`]:             https://docs.phpunit.de/en/9.6/assertions.html#assertstringcontainsstring
+[`Assert::assertStringContainsStringIgnoringCase()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertstringcontainsstringignoringcase
+[`Assert::assertStringNotContainsStringIgnoringCase()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertstringcontainsstringignoringcase
 
 #### PHPUnit < 7.5.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertEqualsSpecializations`
 
@@ -311,12 +311,12 @@ Polyfills the following methods:
 
 These methods were introduced in PHPUnit 7.5.0 as alternatives to using `Assert::assertEquals()` and `Assert::assertNotEquals()` with these optional parameters. Passing the respective optional parameters to these methods was soft deprecated in PHPUnit 7.5.0, hard deprecated (warning) in PHPUnit 8.0.0 and removed in PHPUnit 9.0.0.
 
-[`Assert::assertEqualsCanonicalizing()`]:    https://phpunit.readthedocs.io/en/main/assertions.html#assertequalscanonicalizing
-[`Assert::assertNotEqualsCanonicalizing()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertequalscanonicalizing
-[`Assert::assertEqualsIgnoringCase()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertequalsignoringcase
-[`Assert::assertNotEqualsIgnoringCase()`]:   https://phpunit.readthedocs.io/en/main/assertions.html#assertequalsignoringcase
-[`Assert::assertEqualsWithDelta()`]:         https://phpunit.readthedocs.io/en/main/assertions.html#assertequalswithdelta
-[`Assert::assertNotEqualsWithDelta()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertequalswithdelta
+[`Assert::assertEqualsCanonicalizing()`]:    https://docs.phpunit.de/en/9.6/assertions.html#assertequalscanonicalizing
+[`Assert::assertNotEqualsCanonicalizing()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertequalscanonicalizing
+[`Assert::assertEqualsIgnoringCase()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertequalsignoringcase
+[`Assert::assertNotEqualsIgnoringCase()`]:   https://docs.phpunit.de/en/9.6/assertions.html#assertequalsignoringcase
+[`Assert::assertEqualsWithDelta()`]:         https://docs.phpunit.de/en/9.6/assertions.html#assertequalswithdelta
+[`Assert::assertNotEqualsWithDelta()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertequalswithdelta
 
 #### PHPUnit < 8.4.0: `Yoast\PHPUnitPolyfills\Polyfills\ExpectPHPException`
 
@@ -331,18 +331,18 @@ Polyfills the following methods:
 These methods were introduced in PHPUnit 8.4.0 as alternatives to using `TestCase::expectException()` et al for expecting PHP native errors, warnings and notices.
 Using `TestCase::expectException*()` for testing PHP native notices was soft deprecated in PHPUnit 8.4.0, hard deprecated (warning) in PHPUnit 9.0.0 and (will be) removed in PHPUnit 10.0.0.
 
-[`expectError()`]:                     https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectErrorMessage()`]:              https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectErrorMessageMatches()`]:       https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectWarning()`]:                   https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectWarningMessage()`]:            https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectWarningMessageMatches()`]:     https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectNotice()`]:                    https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectNoticeMessage()`]:             https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectNoticeMessageMatches()`]:      https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectDeprecation()`]:               https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectDeprecationMessage()`]:        https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
-[`expectDeprecationMessageMatches()`]: https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectError()`]:                     https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectErrorMessage()`]:              https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectErrorMessageMatches()`]:       https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectWarning()`]:                   https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectWarningMessage()`]:            https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectWarningMessageMatches()`]:     https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectNotice()`]:                    https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectNoticeMessage()`]:             https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectNoticeMessageMatches()`]:      https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectDeprecation()`]:               https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectDeprecationMessage()`]:        https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
+[`expectDeprecationMessageMatches()`]: https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-php-errors-warnings-and-notices
 
 #### PHPUnit < 8.4.0: `Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches`
 
@@ -351,7 +351,7 @@ Polyfills the [`TestCase::expectExceptionMessageMatches()`] method.
 This method was introduced in PHPUnit 8.4.0 to improve the name of the `TestCase::expectExceptionMessageRegExp()` method.
 The `TestCase::expectExceptionMessageRegExp()` method was soft deprecated in PHPUnit 8.4.0, hard deprecated (warning) in PHPUnit 8.5.3 and removed in PHPUnit 9.0.0.
 
-[`TestCase::expectExceptionMessageMatches()`]: https://phpunit.readthedocs.io/en/main/writing-tests-for-phpunit.html#testing-exceptions
+[`TestCase::expectExceptionMessageMatches()`]: https://docs.phpunit.de/en/9.6/writing-tests-for-phpunit.html#testing-exceptions
 
 #### PHPUnit < 8.5.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertFileEqualsSpecializations`
 
@@ -396,16 +396,16 @@ Polyfills the following renamed methods:
 These methods were introduced in PHPUnit 9.1.0.
 The original methods these new methods replace were hard deprecated in PHPUnit 9.1.0 and (will be) removed in PHPUnit 10.0.0.
 
-[`Assert::assertIsNotReadable()`]:                 https://phpunit.readthedocs.io/en/main/assertions.html#assertisreadable
-[`Assert::assertIsNotWritable()`]:                 https://phpunit.readthedocs.io/en/main/assertions.html#assertiswritable
-[`Assert::assertDirectoryDoesNotExist()`]:         https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryexists
-[`Assert::assertDirectoryIsNotReadable()`]:        https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryisreadable
-[`Assert::assertDirectoryIsNotWritable()`]:        https://phpunit.readthedocs.io/en/main/assertions.html#assertdirectoryiswritable
-[`Assert::assertFileDoesNotExist()`]:              https://phpunit.readthedocs.io/en/main/assertions.html#assertfileexists
-[`Assert::assertFileIsNotReadable()`]:             https://phpunit.readthedocs.io/en/main/assertions.html#assertfileisreadable
-[`Assert::assertFileIsNotWritable()`]:             https://phpunit.readthedocs.io/en/main/assertions.html#assertfileiswritable
-[`Assert::assertMatchesRegularExpression()`]:      https://phpunit.readthedocs.io/en/main/assertions.html#assertmatchesregularexpression
-[`Assert::assertDoesNotMatchRegularExpression()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertmatchesregularexpression
+[`Assert::assertIsNotReadable()`]:                 https://docs.phpunit.de/en/9.6/assertions.html#assertisreadable
+[`Assert::assertIsNotWritable()`]:                 https://docs.phpunit.de/en/9.6/assertions.html#assertiswritable
+[`Assert::assertDirectoryDoesNotExist()`]:         https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryexists
+[`Assert::assertDirectoryIsNotReadable()`]:        https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryisreadable
+[`Assert::assertDirectoryIsNotWritable()`]:        https://docs.phpunit.de/en/9.6/assertions.html#assertdirectoryiswritable
+[`Assert::assertFileDoesNotExist()`]:              https://docs.phpunit.de/en/9.6/assertions.html#assertfileexists
+[`Assert::assertFileIsNotReadable()`]:             https://docs.phpunit.de/en/9.6/assertions.html#assertfileisreadable
+[`Assert::assertFileIsNotWritable()`]:             https://docs.phpunit.de/en/9.6/assertions.html#assertfileiswritable
+[`Assert::assertMatchesRegularExpression()`]:      https://docs.phpunit.de/en/9.6/assertions.html#assertmatchesregularexpression
+[`Assert::assertDoesNotMatchRegularExpression()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertmatchesregularexpression
 
 #### PHPUnit < 9.3.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertClosedResource`
 
@@ -463,7 +463,7 @@ The `assertObjectEquals()` assertion was introduced in PHPUnit 9.4.0.
 
 [limitations in how this assertion is implemented in PHPUnit]: https://github.com/sebastianbergmann/phpunit/issues/4707
 
-[`Assert::assertObjectEquals()`]: https://phpunit.readthedocs.io/en/main/assertions.html#assertobjectequals
+[`Assert::assertObjectEquals()`]: https://docs.phpunit.de/en/9.6/assertions.html#assertobjectequals
 
 
 ### Helper traits
@@ -503,7 +503,7 @@ self::assertSame( $propertyName, self::getProperty( $objInstance, $propertyName
 PHPUnit 8.0.0 introduced a `void` return type declaration to the ["fixture" methods] - `setUpBeforeClass()`, `setUp()`, `tearDown()` and `tearDownAfterClass()`.
 As the `void` return type was not introduced until PHP 7.1, this makes it more difficult to create cross-version compatible tests when using fixtures, due to signature mismatches.
 
-["fixture" methods]: https://phpunit.readthedocs.io/en/main/fixtures.html
+["fixture" methods]: https://docs.phpunit.de/en/9.6/fixtures.html
 
 This library contains two basic `TestCase` options to overcome this issue.
 
@@ -567,10 +567,10 @@ This `TestCase` overcomes the signature mismatch by using the PHPUnit `@before[C
 When using this TestCase, overloaded fixture methods need to use the [`@beforeClass`], [`@before`], [`@after`] and [`@afterClass`] annotations.
 The naming of the overloaded methods is open as long as the method names don't conflict with the PHPUnit native method names.
 
-[`@beforeClass`]: https://phpunit.readthedocs.io/en/main/annotations.html#beforeclass
-[`@before`]:      https://phpunit.readthedocs.io/en/main/annotations.html#before
-[`@after`]:       https://phpunit.readthedocs.io/en/main/annotations.html#after
-[`@afterClass`]:  https://phpunit.readthedocs.io/en/main/annotations.html#afterclass
+[`@beforeClass`]: https://docs.phpunit.de/en/9.6/annotations.html#beforeclass
+[`@before`]:      https://docs.phpunit.de/en/9.6/annotations.html#before
+[`@after`]:       https://docs.phpunit.de/en/9.6/annotations.html#after
+[`@afterClass`]:  https://docs.phpunit.de/en/9.6/annotations.html#afterclass
 
 ```php
 use Yoast\PHPUnitPolyfills\TestCases\XTestCase;

From e2e5a43e0242b16cbeeb6609d64b7b3fbf986d51 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 12 Mar 2023 18:24:10 +0100
Subject: [PATCH 15/22] Tests: remove some duplicate code

---
 .../AssertClosedResourceNotResourceTest.php   | 24 ++++++++++----
 .../AssertClosedResourceTestCase.php          | 29 +++++++++-------
 tests/Polyfills/AssertStringContainsTest.php  | 33 +++++++++++--------
 3 files changed, 53 insertions(+), 33 deletions(-)

diff --git a/tests/Polyfills/AssertClosedResourceNotResourceTest.php b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
index 912b60f..a4057fd 100644
--- a/tests/Polyfills/AssertClosedResourceNotResourceTest.php
+++ b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
@@ -31,14 +31,9 @@ final class AssertClosedResourceNotResourceTest extends TestCase {
 	 * @return void
 	 */
 	public function testAssertIsClosedResource( $value ) {
-		$pattern   = '`^Failed asserting that .+? is of type ["]?resource \(closed\)["]?`s';
-		$exception = 'PHPUnit\Framework\AssertionFailedError';
-		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
-			// PHPUnit < 6.
-			$exception = 'PHPUnit_Framework_AssertionFailedError';
-		}
+		$pattern = '`^Failed asserting that .+? is of type ["]?resource \(closed\)["]?`s';
 
-		$this->expectException( $exception );
+		$this->expectException( $this->getAssertionFailedExceptionName() );
 		$this->expectExceptionMessageMatches( $pattern );
 
 		$this->assertIsClosedResource( $value );
@@ -89,4 +84,19 @@ public static function dataNotResource() {
 			'object'          => [ new stdClass() ],
 		];
 	}
+
+	/**
+	 * Helper function: retrieve the name of the "assertion failed" exception to expect (PHPUnit cross-version).
+	 *
+	 * @return string
+	 */
+	public function getAssertionFailedExceptionName() {
+		$exception = 'PHPUnit\Framework\AssertionFailedError';
+		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
+			// PHPUnit < 6.
+			$exception = 'PHPUnit_Framework_AssertionFailedError';
+		}
+
+		return $exception;
+	}
 }
diff --git a/tests/Polyfills/AssertClosedResourceTestCase.php b/tests/Polyfills/AssertClosedResourceTestCase.php
index 8b1eba6..876e9c6 100644
--- a/tests/Polyfills/AssertClosedResourceTestCase.php
+++ b/tests/Polyfills/AssertClosedResourceTestCase.php
@@ -24,14 +24,9 @@ abstract class AssertClosedResourceTestCase extends TestCase {
 	 * @return void
 	 */
 	public function isClosedResourceExpectExceptionOnOpenResource( $actual ) {
-		$pattern   = '`^Failed asserting that .+? is of type ["]?resource \(closed\)["]?`';
-		$exception = 'PHPUnit\Framework\AssertionFailedError';
-		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
-			// PHPUnit < 6.
-			$exception = 'PHPUnit_Framework_AssertionFailedError';
-		}
+		$pattern = '`^Failed asserting that .+? is of type ["]?resource \(closed\)["]?`';
 
-		$this->expectException( $exception );
+		$this->expectException( $this->getAssertionFailedExceptionName() );
 		$this->expectExceptionMessageMatches( $pattern );
 
 		$this->assertIsClosedResource( $actual );
@@ -49,16 +44,26 @@ public function isNotClosedResourceExpectExceptionOnClosedResource( $actual ) {
 		 * PHPUnit itself will report closed resources as `NULL` prior to Exporter 3.0.4/4.1.4.
 		 * See: https://github.com/sebastianbergmann/exporter/pull/37
 		 */
-		$pattern   = '`^Failed asserting that (resource \(closed\)|NULL) is not of type ["]?resource \(closed\)["]?`';
+		$pattern = '`^Failed asserting that (resource \(closed\)|NULL) is not of type ["]?resource \(closed\)["]?`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		self::assertIsNotClosedResource( $actual );
+	}
+
+	/**
+	 * Helper function: retrieve the name of the "assertion failed" exception to expect (PHPUnit cross-version).
+	 *
+	 * @return string
+	 */
+	public function getAssertionFailedExceptionName() {
 		$exception = 'PHPUnit\Framework\AssertionFailedError';
 		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
 			// PHPUnit < 6.
 			$exception = 'PHPUnit_Framework_AssertionFailedError';
 		}
 
-		$this->expectException( $exception );
-		$this->expectExceptionMessageMatches( $pattern );
-
-		self::assertIsNotClosedResource( $actual );
+		return $exception;
 	}
 }
diff --git a/tests/Polyfills/AssertStringContainsTest.php b/tests/Polyfills/AssertStringContainsTest.php
index 18b31ca..1e5ca3c 100644
--- a/tests/Polyfills/AssertStringContainsTest.php
+++ b/tests/Polyfills/AssertStringContainsTest.php
@@ -102,14 +102,9 @@ public function testAssertStringContainsStringIgnoringCaseEmptyNeedle() {
 	 * @return void
 	 */
 	public function testAssertStringNotContainsStringEmptyNeedle( $haystack ) {
-		$msg       = "Failed asserting that '{$haystack}' does not contain \"\".";
-		$exception = 'PHPUnit\Framework\AssertionFailedError';
-		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
-			// PHPUnit < 6.
-			$exception = 'PHPUnit_Framework_AssertionFailedError';
-		}
+		$msg = "Failed asserting that '{$haystack}' does not contain \"\".";
 
-		$this->expectException( $exception );
+		$this->expectException( $this->getAssertionFailedExceptionName() );
 		$this->expectExceptionMessage( $msg );
 
 		self::assertStringNotContainsString( '', $haystack );
@@ -127,14 +122,9 @@ public function testAssertStringNotContainsStringEmptyNeedle( $haystack ) {
 	 * @return void
 	 */
 	public function testAssertStringNotContainsStringIgnoringCaseEmptyNeedle() {
-		$msg       = 'Failed asserting that \'text with whitespace\' does not contain "".';
-		$exception = 'PHPUnit\Framework\AssertionFailedError';
-		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
-			// PHPUnit < 6.
-			$exception = 'PHPUnit_Framework_AssertionFailedError';
-		}
+		$msg = 'Failed asserting that \'text with whitespace\' does not contain "".';
 
-		$this->expectException( $exception );
+		$this->expectException( $this->getAssertionFailedExceptionName() );
 		$this->expectExceptionMessage( $msg );
 
 		$this->assertStringNotContainsStringIgnoringCase( '', 'text with whitespace' );
@@ -154,4 +144,19 @@ public static function dataHaystacks() {
 			'empty haystack'     => [ '' ],
 		];
 	}
+
+	/**
+	 * Helper function: retrieve the name of the "assertion failed" exception to expect (PHPUnit cross-version).
+	 *
+	 * @return string
+	 */
+	public function getAssertionFailedExceptionName() {
+		$exception = 'PHPUnit\Framework\AssertionFailedError';
+		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
+			// PHPUnit < 6.
+			$exception = 'PHPUnit_Framework_AssertionFailedError';
+		}
+
+		return $exception;
+	}
 }

From cc18f1bb28fe2f8138be032c9f8a311f89734d4e Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 12 Mar 2023 19:59:10 +0100
Subject: [PATCH 16/22] AssertClosedResource: improve handling of custom error
 message

The assertions in the `AssertClosedResource` trait generate a specific error message.
However, if a custom `$message` parameter was passed, that message would not be displayed and only the custom `$message` would be shown when the assertion failed.

As the PHPUnit native error message from the _underlying_ assertion used - _"true is not false"_ - would be obscuring the real issue, this commit adjusts the code to always display the assertion specific error message as well.

Includes tests safeguarding the fix.
---
 src/Polyfills/AssertClosedResource.php        | 28 +++++++++-------
 .../AssertClosedResourceNotResourceTest.php   | 33 +++++++++++++++++++
 2 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/src/Polyfills/AssertClosedResource.php b/src/Polyfills/AssertClosedResource.php
index 9ac30e5..799b6d9 100644
--- a/src/Polyfills/AssertClosedResource.php
+++ b/src/Polyfills/AssertClosedResource.php
@@ -25,12 +25,14 @@ trait AssertClosedResource {
 	 * @return void
 	 */
 	public static function assertIsClosedResource( $actual, $message = '' ) {
-		if ( $message === '' ) {
-			$exporter = \class_exists( 'SebastianBergmann\Exporter\Exporter' ) ? new Exporter() : new Exporter_In_Phar();
-			$message  = \sprintf( 'Failed asserting that %s is of type "resource (closed)"', $exporter->export( $actual ) );
+		$exporter = \class_exists( 'SebastianBergmann\Exporter\Exporter' ) ? new Exporter() : new Exporter_In_Phar();
+		$msg      = \sprintf( 'Failed asserting that %s is of type "resource (closed)"', $exporter->export( $actual ) );
+
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertTrue( ResourceHelper::isClosedResource( $actual ), $message );
+		static::assertTrue( ResourceHelper::isClosedResource( $actual ), $msg );
 	}
 
 	/**
@@ -42,16 +44,18 @@ public static function assertIsClosedResource( $actual, $message = '' ) {
 	 * @return void
 	 */
 	public static function assertIsNotClosedResource( $actual, $message = '' ) {
-		if ( $message === '' ) {
-			$exporter = \class_exists( 'SebastianBergmann\Exporter\Exporter' ) ? new Exporter() : new Exporter_In_Phar();
-			$type     = $exporter->export( $actual );
-			if ( $type === 'NULL' ) {
-				$type = 'resource (closed)';
-			}
-			$message = \sprintf( 'Failed asserting that %s is not of type "resource (closed)"', $type );
+		$exporter = \class_exists( 'SebastianBergmann\Exporter\Exporter' ) ? new Exporter() : new Exporter_In_Phar();
+		$type     = $exporter->export( $actual );
+		if ( $type === 'NULL' ) {
+			$type = 'resource (closed)';
+		}
+		$msg = \sprintf( 'Failed asserting that %s is not of type "resource (closed)"', $type );
+
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertFalse( ResourceHelper::isClosedResource( $actual ), $message );
+		static::assertFalse( ResourceHelper::isClosedResource( $actual ), $msg );
 	}
 
 	/**
diff --git a/tests/Polyfills/AssertClosedResourceNotResourceTest.php b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
index a4057fd..4b7445c 100644
--- a/tests/Polyfills/AssertClosedResourceNotResourceTest.php
+++ b/tests/Polyfills/AssertClosedResourceNotResourceTest.php
@@ -39,6 +39,21 @@ public function testAssertIsClosedResource( $value ) {
 		$this->assertIsClosedResource( $value );
 	}
 
+	/**
+	 * Verify that the assertIsClosedResource() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testAssertIsClosedResourceFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that .+? is of type ["]?resource \(closed\)["]?`s';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$this->assertIsClosedResource( 'text string', 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify that the assertIsNotClosedResource() method passes the test when the variable
 	 * passed is not a resource.
@@ -53,6 +68,24 @@ public function testAssertIsNotClosedResource( $value ) {
 		self::assertIsNotClosedResource( $value );
 	}
 
+	/**
+	 * Verify that the assertIsNotClosedResource() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testAssertIsNotClosedResourceFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that .+? not of type ["]?resource \(closed\)["]?`s';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$resource = \opendir( __DIR__ . '/Fixtures/' );
+		\closedir( $resource );
+
+		$this->assertIsNotClosedResource( $resource, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify that the shouldClosedResourceAssertionBeSkipped() method returns true for non-resources.
 	 *

From dd6b6c12b9e24a75776ba4136287a5b58779c9b6 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 12 Mar 2023 19:59:57 +0100
Subject: [PATCH 17/22] AssertFileDirectory: improve handling of custom error
 message

Some of the assertions in the `AssertFileDirectory` trait generate a specific error message.
However, if a custom `$message` parameter was passed, that message would not be displayed and only the custom `$message` would be shown when the assertion failed.

As the PHPUnit native error message from the _underlying_ assertion used - _"true is not false"_ - would be obscuring the real issue, this commit adjusts the code to always display the assertion specific error message as well.

Includes tests safeguarding the fix.
---
 src/Polyfills/AssertFileDirectory.php       |  42 ++++---
 tests/Polyfills/AssertFileDirectoryTest.php | 121 ++++++++++++++++++++
 2 files changed, 145 insertions(+), 18 deletions(-)

diff --git a/src/Polyfills/AssertFileDirectory.php b/src/Polyfills/AssertFileDirectory.php
index 8f3d771..8ca4015 100644
--- a/src/Polyfills/AssertFileDirectory.php
+++ b/src/Polyfills/AssertFileDirectory.php
@@ -32,11 +32,12 @@ public static function assertIsReadable( $filename, $message = '' ) {
 			throw PHPUnit_Util_InvalidArgumentHelper::factory( 1, 'string' );
 		}
 
-		if ( $message === '' ) {
-			$message = \sprintf( 'Failed asserting that "%s" is readable', $filename );
+		$msg = \sprintf( 'Failed asserting that "%s" is readable', $filename );
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertTrue( \is_readable( $filename ), $message );
+		static::assertTrue( \is_readable( $filename ), $msg );
 	}
 
 	/**
@@ -54,11 +55,12 @@ public static function assertNotIsReadable( $filename, $message = '' ) {
 			throw PHPUnit_Util_InvalidArgumentHelper::factory( 1, 'string' );
 		}
 
-		if ( $message === '' ) {
-			$message = \sprintf( 'Failed asserting that "%s" is not readable', $filename );
+		$msg = \sprintf( 'Failed asserting that "%s" is not readable', $filename );
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertFalse( \is_readable( $filename ), $message );
+		static::assertFalse( \is_readable( $filename ), $msg );
 	}
 
 	/**
@@ -76,11 +78,12 @@ public static function assertIsWritable( $filename, $message = '' ) {
 			throw PHPUnit_Util_InvalidArgumentHelper::factory( 1, 'string' );
 		}
 
-		if ( $message === '' ) {
-			$message = \sprintf( 'Failed asserting that "%s" is writable', $filename );
+		$msg = \sprintf( 'Failed asserting that "%s" is writable', $filename );
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertTrue( \is_writable( $filename ), $message );
+		static::assertTrue( \is_writable( $filename ), $msg );
 	}
 
 	/**
@@ -98,11 +101,12 @@ public static function assertNotIsWritable( $filename, $message = '' ) {
 			throw PHPUnit_Util_InvalidArgumentHelper::factory( 1, 'string' );
 		}
 
-		if ( $message === '' ) {
-			$message = \sprintf( 'Failed asserting that "%s" is not writable', $filename );
+		$msg = \sprintf( 'Failed asserting that "%s" is not writable', $filename );
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertFalse( \is_writable( $filename ), $message );
+		static::assertFalse( \is_writable( $filename ), $msg );
 	}
 
 	/**
@@ -120,11 +124,12 @@ public static function assertDirectoryExists( $directory, $message = '' ) {
 			throw PHPUnit_Util_InvalidArgumentHelper::factory( 1, 'string' );
 		}
 
-		if ( $message === '' ) {
-			$message = \sprintf( 'Failed asserting that directory "%s" exists', $directory );
+		$msg = \sprintf( 'Failed asserting that directory "%s" exists', $directory );
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertTrue( \is_dir( $directory ), $message );
+		static::assertTrue( \is_dir( $directory ), $msg );
 	}
 
 	/**
@@ -142,11 +147,12 @@ public static function assertDirectoryNotExists( $directory, $message = '' ) {
 			throw PHPUnit_Util_InvalidArgumentHelper::factory( 1, 'string' );
 		}
 
-		if ( $message === '' ) {
-			$message = \sprintf( 'Failed asserting that directory "%s" does not exist', $directory );
+		$msg = \sprintf( 'Failed asserting that directory "%s" does not exist', $directory );
+		if ( $message !== '' ) {
+			$msg = $message . \PHP_EOL . $msg;
 		}
 
-		static::assertFalse( \is_dir( $directory ), $message );
+		static::assertFalse( \is_dir( $directory ), $msg );
 	}
 
 	/**
diff --git a/tests/Polyfills/AssertFileDirectoryTest.php b/tests/Polyfills/AssertFileDirectoryTest.php
index 19cf249..8b52737 100644
--- a/tests/Polyfills/AssertFileDirectoryTest.php
+++ b/tests/Polyfills/AssertFileDirectoryTest.php
@@ -9,6 +9,8 @@
 use Yoast\PHPUnitPolyfills\Polyfills\AssertFileDirectory;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertionRenames;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertIsType;
+use Yoast\PHPUnitPolyfills\Polyfills\ExpectException;
+use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches;
 
 /**
  * Availability test for the functions polyfilled by the AssertFileDirectory trait.
@@ -20,6 +22,8 @@ final class AssertFileDirectoryTest extends TestCase {
 	use AssertFileDirectory;
 	use AssertionRenames;
 	use AssertIsType;
+	use ExpectException; // Needed for PHPUnit < 5.2.0 support.
+	use ExpectExceptionMessageMatches;
 
 	/**
 	 * Verify availability of the assertIsReadable() method.
@@ -61,6 +65,22 @@ public function testAssertIsReadableException() {
 		$this->fail( 'Failed to assert that the expected "invalid argument" exception was thrown' );
 	}
 
+	/**
+	 * Verify that the assertIsReadable() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testAssertIsReadableFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that ".+?" is readable`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$path = __DIR__ . \DIRECTORY_SEPARATOR . 'NotExisting.php';
+		$this->assertIsReadable( $path, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify availability of the assertNotIsReadable() method.
 	 *
@@ -105,6 +125,24 @@ public function testAssertNotIsReadableException() {
 		$this->fail( 'Failed to assert that the expected "invalid argument" exception was thrown' );
 	}
 
+	/**
+	 * Verify that the assertNotIsReadable() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @requires PHPUnit < 9.1.0
+	 *
+	 * @return void
+	 */
+	public function testAssertNotIsReadableFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that ".+?" is not readable`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$path = __DIR__ . \DIRECTORY_SEPARATOR . 'Fixtures/AssertFileDirectory_Readable.txt';
+		$this->assertNotIsReadable( $path, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify availability of the assertIsWritable() method.
 	 *
@@ -145,6 +183,22 @@ public function testAssertIsWritableException() {
 		$this->fail( 'Failed to assert that the expected "invalid argument" exception was thrown' );
 	}
 
+	/**
+	 * Verify that the assertIsWritable() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testAssertIsWritableFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that ".+?" is writable`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$path = __DIR__ . \DIRECTORY_SEPARATOR . 'NotExisting' . \DIRECTORY_SEPARATOR;
+		$this->assertIsWritable( $path, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify availability of the assertNotIsWritable() method.
 	 *
@@ -189,6 +243,24 @@ public function testAssertNotIsWritableException() {
 		$this->fail( 'Failed to assert that the expected "invalid argument" exception was thrown' );
 	}
 
+	/**
+	 * Verify that the assertNotIsWritable() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @requires PHPUnit < 9.1.0
+	 *
+	 * @return void
+	 */
+	public function testAssertNotIsWritableFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that ".+?" is not writable`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$path = __DIR__ . \DIRECTORY_SEPARATOR . 'Fixtures/AssertFileDirectory_Readable.txt';
+		$this->assertNotIsWritable( $path, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify availability of the assertDirectoryExists() method.
 	 *
@@ -229,6 +301,22 @@ public function testAssertDirectoryExistsException() {
 		$this->fail( 'Failed to assert that the expected "invalid argument" exception was thrown' );
 	}
 
+	/**
+	 * Verify that the assertDirectoryExists() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testAssertDirectoryExistsFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that directory ".+?" exists`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$path = __DIR__ . \DIRECTORY_SEPARATOR . 'NotExisting' . \DIRECTORY_SEPARATOR;
+		$this->assertDirectoryExists( $path, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify availability of the assertDirectoryNotExists() method.
 	 *
@@ -273,6 +361,24 @@ public function testAssertDirectoryNotExistsException() {
 		$this->fail( 'Failed to assert that the expected "invalid argument" exception was thrown' );
 	}
 
+	/**
+	 * Verify that the assertDirectoryNotExists() method fails a test with the correct custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @requires PHPUnit < 9.1.0
+	 *
+	 * @return void
+	 */
+	public function testAssertDirectoryNotExistsFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that directory ".+?" does not exist`';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$path = __DIR__ . \DIRECTORY_SEPARATOR . 'Fixtures' . \DIRECTORY_SEPARATOR;
+		$this->assertDirectoryNotExists( $path, 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Verify availability of the assertDirectoryIsReadable() method.
 	 *
@@ -405,4 +511,19 @@ public function testAssertFileNotIsWritable() {
 		\chmod( $tempFile, \octdec( '755' ) );
 		\unlink( $tempFile );
 	}
+
+	/**
+	 * Helper function: retrieve the name of the "assertion failed" exception to expect (PHPUnit cross-version).
+	 *
+	 * @return string
+	 */
+	public function getAssertionFailedExceptionName() {
+		$exception = 'PHPUnit\Framework\AssertionFailedError';
+		if ( \class_exists( 'PHPUnit_Framework_AssertionFailedError' ) ) {
+			// PHPUnit < 6.
+			$exception = 'PHPUnit_Framework_AssertionFailedError';
+		}
+
+		return $exception;
+	}
 }

From e87368322ca5d1595b3beb9d4d4bb19049bad74f Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 12 Mar 2023 20:01:10 +0100
Subject: [PATCH 18/22] AssertStringContains: improve handling of custom error
 message

Some of the assertions in the `AssertStringContains` trait generate a specific error message.
However, if a custom `$message` parameter was passed, that message would not be displayed and only the custom `$message` would be shown when the assertion failed.

As the PHPUnit native error message from the _underlying_ assertion used - _"true is not false"_ - would be obscuring the real issue, this commit adjusts the code to always display the assertion specific error message as well.

Includes tests safeguarding the fix.
---
 src/Polyfills/AssertStringContains.php       | 14 +++++----
 tests/Polyfills/AssertStringContainsTest.php | 32 ++++++++++++++++++++
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/src/Polyfills/AssertStringContains.php b/src/Polyfills/AssertStringContains.php
index 4f226ab..1e6ec81 100644
--- a/src/Polyfills/AssertStringContains.php
+++ b/src/Polyfills/AssertStringContains.php
@@ -69,11 +69,12 @@ public static function assertStringContainsStringIgnoringCase( $needle, $haystac
 	 */
 	public static function assertStringNotContainsString( $needle, $haystack, $message = '' ) {
 		if ( $needle === '' ) {
-			if ( $message === '' ) {
-				$message = "Failed asserting that '{$haystack}' does not contain \"{$needle}\".";
+			$msg = "Failed asserting that '{$haystack}' does not contain \"\".";
+			if ( $message !== '' ) {
+				$msg = $message . \PHP_EOL . $msg;
 			}
 
-			static::fail( $message );
+			static::fail( $msg );
 		}
 
 		static::assertNotContains( $needle, $haystack, $message );
@@ -90,11 +91,12 @@ public static function assertStringNotContainsString( $needle, $haystack, $messa
 	 */
 	public static function assertStringNotContainsStringIgnoringCase( $needle, $haystack, $message = '' ) {
 		if ( $needle === '' ) {
-			if ( $message === '' ) {
-				$message = "Failed asserting that '{$haystack}' does not contain \"{$needle}\".";
+			$msg = "Failed asserting that '{$haystack}' does not contain \"\".";
+			if ( $message !== '' ) {
+				$msg = $message . \PHP_EOL . $msg;
 			}
 
-			static::fail( $message );
+			static::fail( $msg );
 		}
 
 		static::assertNotContains( $needle, $haystack, $message, true );
diff --git a/tests/Polyfills/AssertStringContainsTest.php b/tests/Polyfills/AssertStringContainsTest.php
index 1e5ca3c..06d6308 100644
--- a/tests/Polyfills/AssertStringContainsTest.php
+++ b/tests/Polyfills/AssertStringContainsTest.php
@@ -5,6 +5,7 @@
 use PHPUnit\Framework\TestCase;
 use Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains;
 use Yoast\PHPUnitPolyfills\Polyfills\ExpectException;
+use Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches;
 
 /**
  * Availability test for the functions polyfilled by the AssertStringContains trait.
@@ -15,6 +16,7 @@ final class AssertStringContainsTest extends TestCase {
 
 	use AssertStringContains;
 	use ExpectException; // Needed for PHPUnit < 5.2.0 support.
+	use ExpectExceptionMessageMatches;
 
 	/**
 	 * Verify availability of the assertStringContainsString() method.
@@ -145,6 +147,36 @@ public static function dataHaystacks() {
 		];
 	}
 
+	/**
+	 * Verify that the assertStringNotContainsString() method fails a test with a custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testAssertStringNotContainsStringFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that \'.+?\' does not contain ""\.`s';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$this->assertStringNotContainsString( '', 'something', 'This assertion failed for reason XYZ' );
+	}
+
+	/**
+	 * Verify that the assertStringNotContainsStringIgnoringCase() method fails a test with a custom failure message,
+	 * when the custom $message parameter has been passed.
+	 *
+	 * @return void
+	 */
+	public function testssertStringNotContainsStringIgnoringCaseFailsWithCustomMessage() {
+		$pattern = '`^This assertion failed for reason XYZ\s+Failed asserting that \'.+?\' does not contain ""\.`s';
+
+		$this->expectException( $this->getAssertionFailedExceptionName() );
+		$this->expectExceptionMessageMatches( $pattern );
+
+		$this->assertStringNotContainsStringIgnoringCase( '', 'something', 'This assertion failed for reason XYZ' );
+	}
+
 	/**
 	 * Helper function: retrieve the name of the "assertion failed" exception to expect (PHPUnit cross-version).
 	 *

From eab092baa6bea4313d227e30a4323632d5d9e42c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 13 Mar 2023 18:00:36 +0000
Subject: [PATCH 19/22] GH Actions: Bump xt0rted/markdownlint-problem-matcher
 from 1 to 2

Bumps [xt0rted/markdownlint-problem-matcher](https://github.com/xt0rted/markdownlint-problem-matcher) from 1 to 2.
- [Release notes](https://github.com/xt0rted/markdownlint-problem-matcher/releases)
- [Changelog](https://github.com/xt0rted/markdownlint-problem-matcher/blob/main/CHANGELOG.md)
- [Commits](https://github.com/xt0rted/markdownlint-problem-matcher/compare/v1...v2)

---
updated-dependencies:
- dependency-name: xt0rted/markdownlint-problem-matcher
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 .github/workflows/markdown.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
index 5f0fcd5..d7b3435 100644
--- a/.github/workflows/markdown.yml
+++ b/.github/workflows/markdown.yml
@@ -42,7 +42,7 @@ jobs:
 
       # @link https://github.com/marketplace/actions/problem-matcher-for-markdownlint-cli
       - name: Enable showing issue in PRs
-        uses: xt0rted/markdownlint-problem-matcher@v1
+        uses: xt0rted/markdownlint-problem-matcher@v2
 
       - name: Check markdown with CLI2
         run: markdownlint-cli2

From fe4bd4f3ec25adec0bc4c7efcd9d60ab633358ff Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 02:08:05 +0100
Subject: [PATCH 20/22] Updates for branch renames

The `develop` branch has been renamed to `1.x` and a new `2.x` branch will be added to hold development for the `2.x` version.

The `main` branch, from now on, will be used as the release branch for PHPUnit Polyfills 2.x.
---
 .github/RELEASE-CHECKLIST.md | 10 +++++++---
 README.md                    |  2 +-
 composer.json                |  3 +--
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/.github/RELEASE-CHECKLIST.md b/.github/RELEASE-CHECKLIST.md
index cfc5ca0..232eb27 100644
--- a/.github/RELEASE-CHECKLIST.md
+++ b/.github/RELEASE-CHECKLIST.md
@@ -1,8 +1,12 @@
-Template to use for release PRs from `develop` to `main`
+Template to use for release PRs from `#.x` to `main`
 ===========================================================
 
 Title: Release version x.x.x
 
+<!--
+If both a 1.x and a 2.x release are to be tagged, always tag the 1.x release first!
+-->
+
 ## Functional
 - [ ] Confirm that the most recent PHPUnit changelogs have been checked and that the library is still feature complete for those versions supported within the PHPUnit version constraints.
 - [ ] Update the `VERSION` constant in the `phpunitpolyfills-autoload.php` file.
@@ -13,8 +17,8 @@ Title: Release version x.x.x
     Verify that a release link at the bottom of the `CHANGELOG.md` file has been added.
 - [ ] Merge this PR.
 - [ ] Make sure all CI builds are green.
-- [ ] Tag the release (careful, GH defaults to `develop`!).
-- [ ] Create a release from the tag (careful, GH defaults to `develop`!) & copy & paste the changelog to it.
+- [ ] Tag the release (careful, GH defaults to `2.x`!).
+- [ ] Create a release from the tag (careful, GH defaults to `2.x`!) & copy & paste the changelog to it.
     Make sure to copy the links to the issues and the links to the GH usernames from the bottom of the changelog!
 - [ ] Close the milestone.
 - [ ] Open a new milestone for the next release.
diff --git a/README.md b/README.md
index c527cf4..d392091 100644
--- a/README.md
+++ b/README.md
@@ -763,7 +763,7 @@ if ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
 
 Contributing
 ------------
-Contributions to this project are welcome. Clone the repo, branch off from `develop`, make your changes, commit them and send in a pull request.
+Contributions to this project are welcome. Clone the repo, branch off from the oldest #.x branch the patch applies to, make your changes, commit them and send in a pull request against the correct #.x branch.
 
 If you are unsure whether the changes you are proposing would be welcome, please open an issue first to discuss your proposal.
 
diff --git a/composer.json b/composer.json
index 65d4510..2af26d8 100644
--- a/composer.json
+++ b/composer.json
@@ -44,8 +44,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-main": "1.x-dev",
-            "dev-develop": "1.x-dev"
+            "dev-main": "2.x-dev"
         }
     },
     "scripts": {

From fe77f7adcc60e88de051736f890b3f3e2ec15d89 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Fri, 10 Mar 2023 03:03:14 +0100
Subject: [PATCH 21/22] README: add section about PHPUnit support

The README for the 2.x version will be updated to reflect the features supported in the 2.x series.

This commit adds a section to the README for the 1.x branch to inform people about which versions of PHPUnit will be supported by which versions of the PHPUnit Polyfills.
---
 README.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d392091..236c07c 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit
 * [Installation](#installation)
     - [Autoloading](#autoloading)
 * [Why use the PHPUnit Polyfills?](#why-use-the-phpunit-polyfills)
+    - [PHPUnit support](#phpunit-support)
 * [Using this library](#using-this-library)
     - [Supported ways of calling the assertions](#supported-ways-of-calling-the-assertions)
     - [Use with PHPUnit < 5.7.0](#use-with-phpunit--570)
@@ -42,7 +43,7 @@ Installation
 
 To install this package, run:
 ```bash
-composer require --dev yoast/phpunit-polyfills
+composer require --dev yoast/phpunit-polyfills:"^1.0"
 ```
 
 To update this package, run:
@@ -69,6 +70,19 @@ The polyfills have been setup to allow tests to be _forward_-compatible. What th
 This puts the burden of upgrading to use the syntax of newer PHPUnit versions at the point when you want to _start_ running your tests on a newer version.
 By doing so, dropping support for an older PHPUnit version becomes as straight-forward as removing it from the version constraint in your `composer.json` file.
 
+### PHPUnit support
+
+* Releases in the `1.x` series of the PHPUnit Polyfills support PHPUnit 4.8 - 9.x.
+* Releases in the `2.x` series of the PHPUnit Polyfills support PHPUnit 5.7 - 10.x.
+
+Please keep in mind that the PHPUnit Polyfills provide _forward_-compatibility.
+This means that features which PHPUnit no longer supports in PHPUnit 10.x, like expecting PHP deprecation notices or warnings, will not be supported in the PHPUnit Polyfills 2.x series.
+
+Please refer to the [PHPUnit 10 release notification] and [PHPUnit 10 changelog] to inform your decision on whether or not to upgrade (yet).
+
+[PHPUnit 10 release notification]: https://phpunit.de/announcements/phpunit-10.html
+[PHPUnit 10 changelog]:            https://github.com/sebastianbergmann/phpunit/blob/main/ChangeLog-10.0.md
+
 
 Using this library
 ------------------

From 857c550f26910d3261b21a53a48ac7ea751403b0 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Mon, 13 Mar 2023 17:53:24 +0100
Subject: [PATCH 22/22] Changelog for the 1.0.5 release

Includes updating the `VERSION` constant in the `Autoload` class.

Includes minor documentation addition in CI test workflow.
---
 .github/workflows/test.yml    |  2 +-
 CHANGELOG.md                  | 31 +++++++++++++++++++++++++++++++
 phpunitpolyfills-autoload.php |  2 +-
 3 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 4fac066..9f54d16 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -64,7 +64,7 @@ jobs:
 
           # Experimental builds.
           - php: '8.3'
-            phpunit: 'auto'
+            phpunit: 'auto' # PHPUnit 9.x.
             experimental: true
 
           - php: '8.1'
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8d08bd..24a8c92 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,36 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses
 
 _Nothing yet._
 
+## [1.0.5] - 2023-03-31
+
+### Fixed
+* A custom `$message` parameter passed to an assertion, will no longer overrule an emulated "assertion failed" message, but will be prefixed to it instead. PR [#97]
+    This applies to the following polyfills:
+    - `assertIsClosedResource()`
+    - `assertIsNotClosedResource()`
+    - `assertIsReadable()`
+    - `assertNotIsReadable()`
+    - `assertIsWritable()`
+    - `assertNotIsWritable()`
+    - `assertDirectoryExists()`
+    - `assertDirectoryNotExists()`
+    - `assertStringNotContainsString()`
+    - `assertStringNotContainsStringIgnoringCase()`
+
+### Changed
+* The `develop` branch has been removed. Development will now take place in the `1.x` and `2.x` branches.
+* README: links to the PHPUnit manual now point explicitly to the PHPUnit 9.x documentation. PR [#94]
+* README: new sub-section about PHPUnit version support. PR [#99]
+* README: various minor improvements. PRs [#92], [#93]
+* General housekeeping.
+
+[#92]: https://github.com/Yoast/PHPUnit-Polyfills/pull/92
+[#93]: https://github.com/Yoast/PHPUnit-Polyfills/pull/93
+[#94]: https://github.com/Yoast/PHPUnit-Polyfills/pull/94
+[#97]: https://github.com/Yoast/PHPUnit-Polyfills/pull/97
+[#99]: https://github.com/Yoast/PHPUnit-Polyfills/pull/99
+
+
 ## [1.0.4] - 2022-11-16
 
 This is a maintenance release.
@@ -126,6 +156,7 @@ Initial release.
 
 
 [Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/main...HEAD
+[1.0.5]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.4...1.0.5
 [1.0.4]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.3...1.0.4
 [1.0.3]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.2...1.0.3
 [1.0.2]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.1...1.0.2
diff --git a/phpunitpolyfills-autoload.php b/phpunitpolyfills-autoload.php
index d132745..be62abf 100644
--- a/phpunitpolyfills-autoload.php
+++ b/phpunitpolyfills-autoload.php
@@ -17,7 +17,7 @@ final class Autoload {
 		 *
 		 * @var string
 		 */
-		const VERSION = '1.0.4';
+		const VERSION = '1.0.5';
 
 		/**
 		 * Loads a class.