Merge pull request #985 from Kit/block-api-v3

Blocks: Upgrade to apiVersion 3

Author: n7studios

.env.example

@@ -5,8 +5,13 @@ WORDPRESS_ROOT_DIR="/Users/tim/Local Sites/convertkit-github/app/public"
 WORDPRESS_URL=http://kit.local
 
 # Local site DB SQL dump file
+# Set to `tests/Support/Data/dump-6.2.8.sql` when testing in WordPress 6.2.8 or older i.e. to test apiVersion 2 blocks
 WORDPRESS_DB_SQL_DUMP_FILE="tests/Support/Data/dump.sql"
 
+# Use apiVersion 3 of the block editor
+# Set to `false` when testing in WordPress 6.2.8 or older i.e. to test apiVersion 2 blocks
+WORDPRESS_V3_BLOCK_EDITOR_ENABLED=true
+
 # Kit credentials
 CONVERTKIT_OAUTH_ACCESS_TOKEN=
 CONVERTKIT_OAUTH_REFRESH_TOKEN=

.github/workflows/tests-backward-compat.yml

@@ -29,6 +29,7 @@ jobs:
       DB_USER: root
       DB_PASS: root
       DB_HOST: localhost
+      WORDPRESS_V3_BLOCK_EDITOR_ENABLED: false # Test apiVersion 2 blocks against WordPress 6.2.8
       WORDPRESS_DB_SQL_DUMP_FILE: tests/Support/Data/dump-6.2.8.sql # Used to populate the test site database for WordPress 6.2.8
       INSTALL_PLUGINS: "autoptimize debloat litespeed-cache rocket-lazy-load sg-cachepress" # Don't include this repository's Plugin here.
       INSTALL_PLUGINS_URLS: "http://cktestplugins.wpengine.com/wp-content/uploads/2024/11/disable-doing-it-wrong-notices.zip https://downloads.wordpress.org/plugin/block-visibility.3.3.0.zip https://downloads.wordpress.org/plugin/jetpack-boost.3.5.0.zip" # URLs to specific third party Plugins or versions that support WordPress 6.2.8
@@ -134,7 +135,7 @@ jobs:
       - name: Install Paid Third Party WordPress Plugins
         working-directory: ${{ env.ROOT_DIR }}
         run: wp-cli plugin install ${{ secrets.CONVERTKIT_PAID_PLUGIN_URLS }}
-        
+
       # Move Plugin
       - name: Move Plugin
         run: mv /home/runner/work/convertkit-wordpress/convertkit-wordpress/convertkit ${{ env.PLUGIN_DIR }}
@@ -244,6 +245,7 @@ jobs:
         with:
           path: ${{ env.PLUGIN_DIR }}/.env.testing
           contents: |
+            WORDPRESS_V3_BLOCK_EDITOR_ENABLED=${{ env.WORDPRESS_V3_BLOCK_EDITOR_ENABLED }}
             WORDPRESS_DB_SQL_DUMP_FILE=${{ env.WORDPRESS_DB_SQL_DUMP_FILE }}
             CONVERTKIT_API_KEY=${{ env.CONVERTKIT_API_KEY }}
             CONVERTKIT_API_SECRET=${{ env.CONVERTKIT_API_SECRET }}

.github/workflows/tests.yml

@@ -30,7 +30,8 @@ jobs:
       DB_USER: root
       DB_PASS: root
       DB_HOST: localhost
-      WORDPRESS_DB_SQL_DUMP_FILE: tests/Support/Data/dump.sql # Used to populate the test site database for WordPress 6.2.8
+      WORDPRESS_V3_BLOCK_EDITOR_ENABLED: true
+      WORDPRESS_DB_SQL_DUMP_FILE: tests/Support/Data/dump.sql
       INSTALL_PLUGINS: "admin-menu-editor autoptimize beaver-builder-lite-version block-visibility contact-form-7 classic-editor custom-post-type-ui debloat elementor forminator jetpack-boost mailchimp-for-wp rocket-lazy-load woocommerce wordpress-seo wpforms-lite litespeed-cache wp-crontrol wp-super-cache w3-total-cache wp-fastest-cache wp-optimize sg-cachepress" # Don't include this repository's Plugin here.
       INSTALL_PLUGINS_URLS: "https://downloads.wordpress.org/plugin/convertkit-for-woocommerce.1.6.4.zip http://cktestplugins.wpengine.com/wp-content/uploads/2024/01/convertkit-action-filter-tests.zip http://cktestplugins.wpengine.com/wp-content/uploads/2024/11/disable-doing-it-wrong-notices.zip http://cktestplugins.wpengine.com/wp-content/uploads/2025/03/uncode-js_composer.7.8.zip http://cktestplugins.wpengine.com/wp-content/uploads/2025/03/uncode-core.zip" # URLs to specific third party Plugins
       INSTALL_THEMES_URLS: "http://cktestplugins.wpengine.com/wp-content/uploads/2025/03/uncode.zip http://cktestplugins.wpengine.com/wp-content/uploads/2025/04/Divi.zip http://cktestplugins.wpengine.com/wp-content/uploads/2026/01/impeka.zip"
@@ -266,6 +267,7 @@ jobs:
         with:
           path: ${{ env.PLUGIN_DIR }}/.env.testing
           contents: |
+            WORDPRESS_V3_BLOCK_EDITOR_ENABLED=${{ env.WORDPRESS_V3_BLOCK_EDITOR_ENABLED }}
             WORDPRESS_DB_SQL_DUMP_FILE=${{ env.WORDPRESS_DB_SQL_DUMP_FILE }}
             CONVERTKIT_API_KEY=${{ env.CONVERTKIT_API_KEY }}
             CONVERTKIT_API_SECRET=${{ env.CONVERTKIT_API_SECRET }}

TESTING.md

@@ -354,6 +354,29 @@ the Helper's namespace and class under the `enabled` section.
 
 Need to change how Codeception runs?  Edit the [codeception.dist.xml](codeception.dist.xml) file.
 
+## Block Testing
+
+To locally test that Kit Blocks are compatible with apiVersion 2, use the following configuration in `.env.testing`:
+
+| Environment Variable | Value |
+|----------------------|-------|
+| `WORDPRESS_DB_SQL_DUMP_FILE` | `tests/Support/Data/dump-6.2.8.sql` |
+| `WORDPRESS_V3_BLOCK_EDITOR_ENABLED` | `false` |
+
+To locally test that Kit Blocks are compatible with apiVersion 3, use the following configuration in `.env.testing`:
+
+| Environment Variable | Value |
+|----------------------|-------|
+| `WORDPRESS_DB_SQL_DUMP_FILE` | `tests/Support/Data/dump.sql` |
+| `WORDPRESS_V3_BLOCK_EDITOR_ENABLED` | `true` |
+
+GitHub Actions are configured to automatically configure the hosted runner with the applicable SQL dump file and block editor version:
+
+| Workflow File | Description |
+|---------------|-------------|
+| `tests-backward-compat.yml` | Runs tests against WordPress 6.2.8, with apiVersion `2` for blocks |
+| `tests.yml` | Runs tests against the latest WordPress version, with apiVersion `3` for blocks |
+
 ## Writing a WordPress Unit Test
 
 WordPress Unit tests provide testing of Plugin specific functions and/or classes, typically to assert that they perform as expected