Enhancement #6: As a QA engineer, I want the plugin versions to be automatically handled so that I can easily run tests on a selected version

.gitignore

@@ -1,4 +1,5 @@
 /config/wp.config.ts
+/config/plugin.config.ts
 /node_modules
 /artifacts
 /plugin/*.zip
@@ -13,4 +14,8 @@
 .DS_Store
 .idea
 backstop.json
-/temp
+/temp
+/.tmp-plugin-build
+
+#Ignore insiders AI rules
+.github/instructions/codacy.instructions.md

README.md

@@ -4,13 +4,17 @@ E2E tests here are written with Playwright. Without further ado, let's meet belo
 ## Requirements
 - Do you still not have node installed? You'll be needing it.
 - Some tests don't come easy with just Playwright, so you need to install the [helper plugin](https://github.com/wp-media/wp-rocket-e2e-test-helper) on your test site. just download the zip from the repo.
-- You also need zip files of WP Rocket, I'll explain:
-  - zip for new release - **rename the zip file name to `new_release.zip`. e.g `wp-rocket_3.13.1.zip` becomes `new_release.zip`**
-  - zip for previous stable release - **rename the zip file name to `previous_stable`. e.g `wp-rocket_3.13.0.2.zip becomes `previous_stable.zip`**
-  - zip for 3.10.9 - **leave this as `wp-rocket_3.10.9.zip`**
-  - Make sure to put these files in the `./plugin` folder in the root - Playwright will pick these files when needed and use them during tests.
+- **WP Rocket plugin versions are now automatically managed!** 🎉
+  - Configure which versions to use in `config/plugin.config.ts`
+  - The test suite will automatically download/build the required versions
+  - Manual setup is no longer required unless you want to customize versions
 
-  **NB:** Files like the new release and previous stable release are not constant so make sure to always update as your tests fit.
+  **Optional manual management:**
+  - `npm run plugin:setup` - Download/build all configured versions
+  - `npm run plugin:list` - List all plugin files and their status
+  - `npm run plugin:clean` - Remove all plugin files
+  - `npm run plugin:validate` - Check if all required files exist
+  - `npm run plugin:setup -- --force` - Force rebuild even if files exist
 
  ## Installation
  - Clone this repo
@@ -26,6 +30,74 @@ E2E tests here are written with Playwright. Without further ado, let's meet belo
 
  You can find this [here](https://github.com/wp-media/wp-rocket-e2e/blob/trunk/config/wp.config.sample.ts)
 
+ ### Plugin Version Configuration
+
+ Copy `config/plugin.config.sample.ts` to `config/plugin.config.ts` and configure which WP Rocket versions to use for testing. See the sample file for detailed examples and configuration options.
+
+ #### CLI Version Overrides
+
+ You can override plugin versions directly from the command line without modifying the config file! This is useful for quick testing with different versions:
+
+ **Override single version:**
+ ```bash
+ # Test with a specific previous_stable version
+ npm run test:e2e -- --previous-stable=3.16.0
+
+ # Test with a development branch
+ npm run test:e2e -- --new-release=branch:develop
+
+ # Test with a specific tag
+ npm run test:e2e -- --new-release=tag:3.16.1
+ ```
+
+ **Override multiple versions:**
+ ```bash
+ # Override both previous_stable and new_release
+ npm run test:e2e -- --previous-stable=3.16.0 --new-release=3.16.1
+
+ # Mix version numbers with branches
+ npm run test:smoke -- --previous-stable=3.16.0 --new-release=branch:develop
+ ```
+
+ **Using environment variables:**
+ ```bash
+ # Set versions via environment variables
+ PREVIOUS_STABLE=3.16.0 NEW_RELEASE=3.16.1 npm run test:e2e
+
+ # Or export them for multiple test runs
+ export PREVIOUS_STABLE=3.16.0
+ export NEW_RELEASE=branch:develop
+ npm run test:e2e
+ npm run test:smoke
+ ```
+
+ **Supported version formats:**
+ - Version number: `3.16.0` (downloads source from GitHub release tags, then builds with npm/composer - requires GITHUB_TOKEN)
+ - GitHub branch: `branch:develop` or `branch:release/3.16.0` (clones and builds from source - requires GITHUB_TOKEN)
+ - GitHub tag: `tag:3.16.0` (clones and builds from tag - requires GITHUB_TOKEN)
+ - Direct URL: `https://example.com/wp-rocket.zip` (downloads pre-built zip)
+
+ **Available override options:**
+ - `--previous-stable` - Override the previous stable release version
+ - `--new-release` - Override the new release version being tested
+
+ **Examples for common scenarios:**
+ ```bash
+ # Test upgrade from 3.16.0 to latest develop branch
+ npm run test:e2e -- --previous-stable=3.16.0 --new-release=branch:develop
+
+ # Quick smoke test with specific versions
+ npm run test:smoke -- --new-release=3.16.2
+
+ # Visual regression with beta version
+ npm run test:vr -- --new-release=tag:3.16.2-beta5 --wproption=lazyloadCssBgImg
+
+ # Test with locally downloaded zip file
+ npm run test:e2e -- --new-release=https://your-server.com/custom-build.zip
+ ```
+
+ The CLI overrides will automatically trigger a download/build of the specified versions if they're not already in your `plugin/` directory.
+
  ## Running Tests
  - Don't forget to install the [helper plugin](https://github.com/wp-media/wp-rocket-e2e-test-helper)
  - To run tests on playwright, simply run `npx playwright test` or `npm run test:e2e` which ever you prefer.

config/plugin.config.sample.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview
+ * Plugin version configuration sample for WP Rocket E2E tests.
+ * Copy this file to plugin.config.ts and update with your desired versions.
+ * 
+ * The plugin manager will automatically download or build the specified versions
+ * if they are not already present in the plugin/ directory.
+ */
+
+export interface PluginVersionConfig {
+    /**
+     * Previous stable release version.
+     * This will be used for upgrade/downgrade tests.
+     * 
+     * Can be:
+     * - A version number (e.g., '3.16.0') - downloads source from GitHub releases/tags/v{version}, then builds it
+     * - A GitHub branch name prefixed with 'branch:' (e.g., 'branch:release/3.16.0')
+     * - A GitHub tag prefixed with 'tag:' (e.g., 'tag:3.16.0')
+     * - A URL pointing to a zip file (pre-built)
+     */
+    previousStable: string;
+
+    /**
+     * New release version.
+     * This is the main version being tested.
+     * 
+     * Can be:
+     * - A version number (e.g., '3.16.1') - downloads source from GitHub releases/tags/v{version}, then builds it
+     * - A GitHub branch name prefixed with 'branch:' (e.g., 'branch:develop')
+     * - A GitHub tag prefixed with 'tag:' (e.g., 'tag:3.16.1')
+     * - A URL pointing to a zip file (pre-built)
+     */
+    newRelease: string;
+
+    /**
+     * GitHub repository information.
+     * Required for downloading from GitHub (version numbers, branches, or tags).
+     * The token is needed to access private repository releases.
+     */
+    repository?: {
+        owner: string;
+        name: string;
+        /**
+         * Personal Access Token for GitHub API (if needed for private repos or rate limits).
+         * Can also be set via GITHUB_TOKEN environment variable.
+         */
+        token?: string;
+    };
+}
+
+/**
+ * Plugin version configuration.
+ * 
+ * @example
+ * // Using version numbers (downloads from GitHub releases)
+ * export const pluginConfig: PluginVersionConfig = {
+ *     previousStable: '3.16.0',
+ *     newRelease: '3.16.1',
+ *     repository: {
+ *         owner: 'wp-media',
+ *         name: 'wp-rocket',
+ *         token: process.env.GITHUB_TOKEN
+ *     }
+ * };
+ * 
+ * @example
+ * // Using GitHub branches
+ * export const pluginConfig: PluginVersionConfig = {
+ *     previousStable: 'branch:release/3.16.0',
+ *     newRelease: 'branch:develop',
+ *     repository: {
+ *         owner: 'wp-media',
+ *         name: 'wp-rocket',
+ *         token: process.env.GITHUB_TOKEN
+ *     }
+ * };
+ * 
+ * @example
+ * // Using direct URLs
+ * export const pluginConfig: PluginVersionConfig = {
+ *     previousStable: 'https://example.com/wp-rocket-3.16.0.zip',
+ *     newRelease: 'https://example.com/wp-rocket-3.16.1.zip',
+ * };
+ */
+export const pluginConfig: PluginVersionConfig = {
+    // Configure the versions you want to test here
+    previousStable: '3.20.1',  // Previous stable version
+
+    // NOTE: Pre-release (beta) versions like '3.20.2-beta5' may not be available at the standard release URL.
+    // If you need to test a beta version, use a direct URL or a GitHub tag/branch instead (see examples above).
+    newRelease: '3.20.2',      // Latest stable version to test
+
+    // Optional: Configure GitHub repository for branch-based builds
+    repository: {
+        owner: 'wp-media',
+        name: 'wp-rocket',
+        token: process.env.GITHUB_TOKEN,
+    }
+};

package.json

@@ -30,11 +30,16 @@
     "test:performancehints": "$npm_package_config_testCommand --tags @performancehints",
     "healthcheck": "ts-node healthcheck.ts",
     "push-report": "ts-node report.ts",
+    "open-report": "open ./test-results/cucumber-report.html",
     "wp-env": "wp-env",
     "test:bwpupstorage": "$npm_package_config_testCommand --tags @bwpupstorage",
     "test:bwpuponboarding": "$npm_package_config_testCommand --tags @bwpuponboarding",
     "test:bwpupsmoke": "$npm_package_config_testCommand --tags @bwpupsmoke",
-    "test:bwpup": "$npm_package_config_testCommand --tags @bwpup"
+    "test:bwpup": "$npm_package_config_testCommand --tags @bwpup",
+    "plugin:setup": "ts-node plugin-manager-cli.ts setup",
+    "plugin:list": "ts-node plugin-manager-cli.ts list",
+    "plugin:clean": "ts-node plugin-manager-cli.ts clean",
+    "plugin:validate": "ts-node plugin-manager-cli.ts validate"
   },
   "repository": {
     "type": "git",

plugin-manager-cli.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview
+ * CLI tool for managing WP Rocket plugin versions for E2E tests.
+ * 
+ * Usage:
+ *   npm run plugin:setup              - Setup all configured plugin versions
+ *   npm run plugin:setup -- --force   - Force rebuild/re-download even if files exist
+ *   npm run plugin:list               - List all plugin files and their status
+ *   npm run plugin:clean              - Remove all plugin files
+ *   npm run plugin:validate           - Check if all required plugin files exist
+ */
+
+import { setupPluginVersions, listPluginFiles, cleanPluginFiles, validatePluginFiles } from './utils/plugin-manager';
+
+const args = process.argv.slice(2);
+const command = args[0] || 'setup';
+const force = args.includes('--force') || args.includes('-f');
+
+async function main(): Promise<void> {
+    try {
+        switch (command) {
+            case 'setup':
+                await setupPluginVersions(force);
+                break;
+
+            case 'list':
+                await listPluginFiles();
+                break;
+
+            case 'clean':
+                await cleanPluginFiles();
+                break;
+
+            case 'validate': {
+                const isValid = await validatePluginFiles();
+                if (isValid) {
+                    console.log('✅ All required plugin files are present\n');
+                    process.exit(0);
+                } else {
+                    console.log('❌ Some required plugin files are missing\n');
+                    console.log('Run "npm run plugin:setup" to download/build them.\n');
+                    process.exit(1);
+                }
+                break;
+            }
+
+            case 'help':
+            case '--help':
+            case '-h':
+                printHelp();
+                break;
+
+            default:
+                console.error(`Unknown command: ${command}`);
+                printHelp();
+                process.exit(1);
+        }
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error('Error:', errorMessage);
+        process.exit(1);
+    }
+}
+
+function printHelp(): void {
+    console.log(`
+WP Rocket Plugin Manager
+
+Usage: npm run plugin:<command> [options]
+
+Commands:
+  setup                Setup all configured plugin versions
+  list                 List all plugin files and their status
+  clean                Remove all plugin files
+  validate             Check if all required plugin files exist
+  help                 Show this help message
+
+Options:
+  --force, -f         Force rebuild/re-download even if files exist
+
+Examples:
+  npm run plugin:setup
+  npm run plugin:setup -- --force
+  npm run plugin:list
+  npm run plugin:clean
+  npm run plugin:validate
+
+Configuration:
+  Edit config/plugin.config.ts to configure which plugin versions to use.
+    `);
+}
+
+main();