Merge pull request #260 from wpengine/chore-phpunit-tests-previews-iteration-2

chore:  Preview Unit Tests - Iteration 2

Author: colinmurphy

.github/actions/codeception/action.yml

@@ -67,36 +67,6 @@ runs:
         WP_VERSION: ${{ inputs.wordpress }}
         PHP_VERSION: ${{ inputs.php }}
 
-    - name: Run Acceptance Tests w/ Docker
-      working-directory: ${{ inputs.working-directory }}
-      shell: bash
-      run: |
-        docker exec \
-          --env DEBUG=${{ env.DEBUG }} \
-          --env SKIP_TESTS_CLEANUP=${{ env.SKIP_TESTS_CLEANUP }} \
-          --env SUITES=acceptance \
-          $(docker compose ps -q wordpress) \
-          bash -c "cd wp-content/plugins/$(basename $(echo ${{ inputs.working-directory }} | sed 's:/*$::')) && bin/run-codeception.sh"
-      env:
-        DEBUG: ${{ env.ACTIONS_STEP_DEBUG }}
-        SKIP_TESTS_CLEANUP: "true"
-      continue-on-error: true
-
-    - name: Run Functional Tests w/ Docker
-      working-directory: ${{ inputs.working-directory }}
-      shell: bash
-      run: |
-        docker exec \
-          --env DEBUG=${{ env.DEBUG }} \
-          --env SKIP_TESTS_CLEANUP=${{ env.SKIP_TESTS_CLEANUP }} \
-          --env SUITES=functional \
-          $(docker compose ps -q wordpress) \
-          bash -c "cd wp-content/plugins/$(basename ${{ inputs.working-directory }}) && bin/run-codeception.sh"
-      env:
-        DEBUG: ${{ env.ACTIONS_STEP_DEBUG }}
-        SKIP_TESTS_CLEANUP: "true"
-      continue-on-error: true
-
     - name: Run WPUnit Tests w/ Docker
       working-directory: ${{ inputs.working-directory }}
       shell: bash

.github/workflows/code-quality.yml

@@ -26,6 +26,14 @@ jobs:
           plugin=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | grep '^plugins/' | head -1 | cut -d/ -f2)
           echo "slug=$plugin" >> $GITHUB_OUTPUT
 
+      # We should at least have a phpcs.xml file to run code quality checks
+      - name: Validate phpcs.xml
+        run: |
+          if [ ! -f "plugins/${{ steps.plugin.outputs.slug }}/phpcs.xml" ]; then
+            echo "Exiting as no phpcs.xml file found for /${{ steps.plugin.outputs.slug }}"
+            exit 1
+          fi
+
       - name: PHP Code Quality
         uses: ./.github/actions/code-quality
         with:

.github/workflows/codeception.yml

@@ -1,4 +1,4 @@
-name: Codeception
+name: Testing Integration
 
 on:
   push:
@@ -43,10 +43,18 @@ jobs:
           plugin=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} | grep '^plugins/' | head -1 | cut -d/ -f2)
           echo "slug=$plugin" >> $GITHUB_OUTPUT
 
+      - name: Validate codeception.dist.yml
+        run: |
+          if [ ! -f "plugins/${{ steps.plugin.outputs.slug }}/codeception.dist.yml" ]; then
+            echo "Exiting as no codeception file found for this plugin - /${{ steps.plugin.outputs.slug }}"
+            exit 1
+          fi
+
       - name: Validate composer.json
         run: |
           if [ ! -f "plugins/${{ steps.plugin.outputs.slug }}/composer.json" ]; then
-            echo "Warning: composer.json missing in plugins/${{ steps.plugin.outputs.slug }}"
+            echo "Exiting as no composer file found for this plugin - ${{ steps.plugin.outputs.slug }}"
+            exit 1
           fi
 
       - name: Run Codeception Tests

.github/workflows/e2e-test.yml

@@ -1,4 +1,4 @@
-name: Playwright End-to-End Tests
+name: End-to-End Tests
 
 on:
   push:

.github/workflows/plugin-artifact-for-pr.yml

@@ -30,6 +30,7 @@ jobs:
           PLUGIN_SLUG: ${{ steps.plugin.outputs.slug }}
         with:
             slug: ${{ env.PLUGIN_SLUG }}
+            composer-options: '--no-progress --optimize-autoloader --no-dev'
 
       - name: Comment with artifact link
         uses: actions/github-script@v7

plugins/hwp-previews/ACTIONS_AND_FILTERS.md

@@ -8,23 +8,33 @@
 
 ## PHP Filters
 
+## Admin
+
+- `hwp_previews_settings_init` - Allows a user to modify the `Settings` instance
+- `hwp_previews_settings_form_manager_init` - Allows a user to modify the `Settings_Form_Manager` instance and update fields and post types
+- `hwp_previews_settings_fields` - Allows a user to register, modify, or remove settings fields for the settings page
+- `hwp_previews_settings_group_option_key` - Filter to modify the settings group option key. Default is HWP_PREVIEWS_SETTINGS_KEY
+- `hwp_previews_settings_group_settings_group` - Filter to modify the settings group name. Default is HWP_PREVIEWS_SETTINGS_GROUP
+
+
+
 - `hwp_previews_register_parameters` - Allows modification of the URL parameters used for previews for the class `Preview_Parameter_Registry`
 - `hwp_previews_template_path` - To use our own template for iframe previews
 - `hwp_previews_core` - Register or unregister URL parameters, and adjust types/statuses
 - `hwp_previews_filter_available_post_types` - Filter to modify the available post types for Previews.
-- `hwp_previews_settings_group_option_key` - Filter to modify the settings group option key. Default is HWP_PREVIEWS_SETTINGS_KEY
-- `hwp_previews_settings_group_settings_group` - Filter to modify the settings group name. Default is HWP_PREVIEWS_SETTINGS_GROUP
+- `hwp_previews_filter_available_post_statuses` - Filter for post statuses for previews for Previews
+- `hwp_previews_filter_available_parent_post_statuses` - Filter for parent post statuses for Previews
 - `hwp_previews_settings_group_settings_config` - Filter to modify the settings array. See `Settings_Group`
 - `hwp_previews_settings_group_cache_groups` - Filter to modify cache groups for `Settings_Group`
 - `hwp_previews_get_post_types_config` - Filter for generating the instance of `Post_Types_Config_Interface`
-- `hwp_previews_hooks_post_type_config` - Filter for post type config service for the Hook class
 - `hwp_previews_hooks_post_status_config` - Filter for post status config service for the Hook class
 - `hwp_previews_hooks_preview_link_service` - Filter for preview link service for the Hook class
-- `hwp_previews_hooks_post_statuses` - Filter for post statuses for previews for the Hook Class
-- `hwp_previews_settings_fields` - Allows a user to register, modify, or remove settings fields for the settings page
 
 ## Usage Examples
 
+@TODO - Redo
+
+
 ### Filter: Post Types List
 
 Modify which post types appear in the settings UI:

plugins/hwp-previews/CHANGELOG.md

@@ -1,5 +1,5 @@
 # HWP Previews
 
-## 0.0.1
+## 0.0.1-beta
 
 - Proof of concept.

plugins/hwp-previews/README.md

@@ -1,11 +1,26 @@
 # HWP Previews
 
-**Headless Previews** solution for WordPress: fully configurable preview URLs via the settings page.
+**Headless Previews** solution for WordPress: fully configurable preview URLs via the settings page which is framework agnostic.
+
+* [Join the Headless WordPress community on Discord.](https://discord.gg/headless-wordpress-836253505944813629)
+* [Documentation](#getting-started)
+
+
+-----
+
+[![Version](https://img.shields.io/badge/version-0.0.1-beta)]()
+[![License](https://img.shields.io/badge/license-GPLv2%2B-green)]()
+![GitHub forks](https://img.shields.io/github/forks/wpengine/hwptoolkit?style=social)
+![GitHub stars](https://img.shields.io/github/stars/wpengine/hwptoolkit?style=social)
+[![Testing Integration](https://github.com/wpengine/hwptoolkit/workflows/Testing%20Integration/badge.svg)](https://github.com/wpengine/hwptoolkit/actions?query=workflow%3A%22Testing+Integration%22)
+[![Code Quality](https://github.com/wpengine/hwptoolkit/workflows/Code%20Quality/badge.svg)](https://github.com/wpengine/hwptoolkit/actions?query=workflow%3A%22Code+Quality%22)
+[![End-to-End Tests](https://github.com/wpengine/hwptoolkit/workflows/End-to-End%20Tests/badge.svg)](https://github.com/wpengine/hwptoolkit/actions?query=workflow%3A%22End-to-End+Tests%22)
+-----
+
 
-[![Version](https://img.shields.io/badge/version-0.0.1-blue)]() [![License](https://img.shields.io/badge/license-GPLv2%2B-lightgrey)]()
 
 > [!CAUTION]
-> This plugin is currently in an alpha state. It's still under active development, so you may encounter bugs or incomplete features. Updates will be rolled out regularly. Use with caution and provide feedback if possible.
+> This plugin is currently in an beta state. It's still under active development, so you may encounter bugs or incomplete features. Updates will be rolled out regularly. Use with caution and provide feedback if possible. You can create an issue at [https://github.com/wpengine/hwptoolkit/issues](https://github.com/wpengine/hwptoolkit/issues)
 
 ---
 
@@ -26,6 +41,11 @@ HWP Previews is a robust and extensible WordPress plugin that centralizes all pr
 It empowers site administrators and developers to tailor preview behaviors for each public post type independently, facilitating seamless headless or decoupled workflows.
 With HWP Previews, you can define dynamic URL templates, enforce unique slugs for drafts, allow all post statuses be used as parent and extend functionality through flexible hooks and filters, ensuring a consistent and conflict-free preview experience across diverse environments.
 
+
+
+>[!IMPORTANT]
+> For Faust users, HWP Previews integrates seamlessly, automatically configuring settings to match Faust's preview system. This allows you to maintain your existing preview workflow without additional setup.
+
 ---
 
 ## Features
@@ -34,8 +54,8 @@ With HWP Previews, you can define dynamic URL templates, enforce unique slugs fo
 - **Custom URL Templates**: Define preview URLs using placeholder tokens for dynamic content.
 - **Parent Status**: Allow posts of **all** statuses to be used as parent within hierarchical post types.
 - **Highly Customizable**: Extend core behavior with a comprehensive set of actions and filters.
+- **Faust Compatibility**: The plugin is compatible with [Faust.js](https://faustjs.org/) and the [FaustWP plugin](https://github.com/wpengine/faustjs/tree/canary/plugins/faustwp).
 
----
 
 ## Getting Started
 
@@ -49,6 +69,28 @@ This guide will help you set up your first headless preview link for the "Posts"
 
 ---
 
+## Project Structure
+
+```text
+hwp-previews/
+├── src/                        # Main plugin source code
+│   ├── Admin/                  # Admin settings, menu, and settings page logic
+│   ├── Hooks/                  # WordPress hooks and filters
+│   ├── Integration/            # Integrations (e.g. Faust)
+│   ├── Preview/                # Preview URL logic, template resolver, helpers
+│   ├── Plugin.php              # Main plugin class (entry point)
+│   └── Autoload.php            # PSR-4 autoloader
+├── tests/                      # All test suites
+│   ├── wpunit/                 # WPBrowser/Codeception unit 
+├── [hwp-previews.php]
+├── [activation.php]
+├── [composer.json]
+├── [deactivation.php]
+├── [ACTIONS_AND_FILTERS.md]
+├── [TESTING.md]
+├── [README.md]
+```
+
 ## Configuration
 
 HWP Previews configuration located at **Settings > HWP Previews** page in your WP Admin. The settings are organized by post type.
@@ -114,11 +156,7 @@ This out-of-the-box configuration allows your existing preview workflow to conti
 
 ---
 
-## Extending the Functionality
-
-The plugin's behavior can be extended using its PHP hooks. Developers can control which post types are configurable in the settings via the `hwp_previews_filter_available_post_types` filter. The `hwp_previews_core` action allows for registering new URL parameters or unregistering default ones. Additionally, the `hwp_previews_template_path` filter can be used to replace the default preview iframe with a custom PHP template.
-
-### Actions & Filters
+## Actions & Filters
 
 See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehensive list of available hooks and how to use them.
 
@@ -127,3 +165,28 @@ See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehe
 ## Testing
 
 See [Testing.md](TESTING.md) for details on how to test the plugin.
+
+
+## Screenshots
+
+<details>
+<summary>Click to expand screenshots</summary>
+
+![Custom Post Type Preview](./screenshots/settings_page.png)
+*Preview settings page.*
+
+![Custom Post Type Preview](./screenshots/cpt_preview.png)
+*Preview settings for a custom post type.*
+
+![Post Preview](./screenshots/post_preview.png)
+*Preview button in the WordPress editor.*
+
+![Post Preview in Iframe](./screenshots/post_preview_iframe.png)
+*Preview loaded inside the WordPress editor using an iframe.*
+
+![Preview Token](./screenshots/preview_token.png)
+*Preview token parameter for secure preview URLs.*
+
+![App Password](./screenshots/app_password.png)
+*App password setup for authentication.*
+</details>

plugins/hwp-previews/TESTING.md

@@ -33,6 +33,7 @@ The plugin provides scripts to set up a local WordPress environment for testing,
 1. **Copy and configure environment variables:**
 
    ```bash
+   @TODO
    cp .env.dist .env
    # Edit .env as needed for your local setup
    ```
@@ -54,44 +55,29 @@ The plugin provides scripts to set up a local WordPress environment for testing,
 
 ## Running Tests
 
-### Unit Tests
+Currently the plugin has the following suite of tests
 
-Run unit tests (no WordPress loaded):
-
-```bash
-composer run test:unit
-# or
-vendor/bin/codecept run unit
-```
+1. WP Unit Tests - (Unit and Integration Tests)
+2. E2E Tests - Playright tests
 
 ### WPUnit (WordPress-aware Unit/Integration) Tests
 
 Run WPUnit tests (WordPress loaded):
 
 ```bash
-composer run test:wpunit
-# or
-vendor/bin/codecept run wpunit
+sh bin/local/run-unit-tests.sh coverage
 ```
 
-### Functional Tests
+> [!IMPORTANT]
+> You can also add coverage e.g. `sh bin/local/run-unit-tests.sh coverage --coverage-html` and the output will be saved in [tests/_output/coverage/dashboard.html](tests/_output/coverage/dashboard.html)
 
-Run functional tests (simulate web requests):
 
-```bash
-composer run test:functional
-# or
-vendor/bin/codecept run functional
-```
-
-### Acceptance Tests
+### E2WTests
 
 Run browser-based acceptance tests:
 
 ```bash
-composer run test:acceptance
-# or
-vendor/bin/codecept run acceptance
+sh bin/local/run-e2e-tests.sh coverage
 ```
 
 ### All Tests
@@ -142,13 +128,7 @@ tests/
 ├── _envs/                # Environment configs
 ├── _output/              # Test output (logs, coverage)
 ├── _support/             # Helper classes, modules
-├── acceptance/           # Acceptance test cases
-├── functional/           # Functional test cases
-├── unit/                 # Unit test cases
 ├── wpunit/               # WPUnit (WordPress-aware unit/integration) test cases
-├── acceptance.suite.dist.yml
-├── functional.suite.dist.yml
-├── unit.suite.dist.yml
 ├── wpunit.suite.dist.yml
 └── wpunit/
     └── bootstrap.php     # Bootstrap for WPUnit tests

plugins/hwp-previews/activation.php

@@ -3,6 +3,8 @@
  * Activation Hook
  *
  * @package HWP\Previews
+ *
+ * @since 0.0.1
  */
 
 declare(strict_types=1);