Merge pull request #245 from stellarwp/2.2.0

Release 2.2.0

Author: defunctl

.env.slic

@@ -16,6 +16,8 @@ CLI_VERBOSITY=0
 # This will force the cli tool to use a specific project to run the tests.
 # You should use the `use` command usually.
 # SLIC_CURRENT_PROJECT=the-events-calendar
+# The container path for the current project. This is managed by the `use` command.
+# SLIC_CURRENT_PROJECT_CONTAINER_PATH=/var/www/html/wp-content/plugins/the-events-calendar
 # When you `here` at the site level, all selected targets via `use` will have a relative path set.
 # SLIC_CURRENT_PROJECT_RELATIVE_PATH=
 # When you `use` on a supported subdirectory of a plugin, this stores the subdirectory name.

.github/workflows/publish-slic-docker-image.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         # The php_version is the docker tag from https://hub.docker.com/_/php/tags
-        php_version: [ '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ]
+        php_version: [ '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5' ]
         arch: [ 'amd64', 'arm64' ]
         # Add runner and platform info for each architecture
         include:
@@ -86,7 +86,7 @@ jobs:
       packages: write
     strategy:
       matrix:
-        php_version: [ '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ]
+        php_version: [ '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5' ]
     steps:
       - name: Log in to the Container registry
         uses: docker/login-action@v3

.github/workflows/publish-wordpress-docker-image.yml

@@ -70,17 +70,39 @@ jobs:
             runner: ubuntu-24.04-arm
             platform: linux/arm64
             arch: arm64
-          # WordPress 6.5 with PHP 8.3 - both architectures
-          - wp_version: '6.5'
+          # WordPress 7.0.0 with PHP 8.3 - both architectures
+          - wp_version: '7.0.0'
             php_version: '8.3'
             runner: ubuntu-latest
             platform: linux/amd64
             arch: amd64
-          - wp_version: '6.5'
+          - wp_version: '7.0.0'
             php_version: '8.3'
             runner: ubuntu-24.04-arm
             platform: linux/arm64
             arch: arm64
+          # WordPress 7.0.0 with PHP 8.4 - both architectures
+          - wp_version: '7.0.0'
+            php_version: '8.4'
+            runner: ubuntu-latest
+            platform: linux/amd64
+            arch: amd64
+          - wp_version: '7.0.0'
+            php_version: '8.4'
+            runner: ubuntu-24.04-arm
+            platform: linux/arm64
+            arch: arm64
+          # WordPress 7.0.0 with PHP 8.5 - both architectures
+          - wp_version: '7.0.0'
+            php_version: '8.5'
+            runner: ubuntu-latest
+            platform: linux/amd64
+            arch: amd64
+          - wp_version: '7.0.0'
+            php_version: '8.5'
+            runner: ubuntu-24.04-arm
+            platform: linux/arm64
+            arch: arm64
 
     steps:
       - name: Checkout repository
@@ -147,6 +169,8 @@ jobs:
           - php_version: '7.3'
           - php_version: '7.4'
           - php_version: '8.3'
+          - php_version: '8.4'
+          - php_version: '8.5'
     steps:
       - name: Log in to the Container registry
         uses: docker/login-action@v3

README.md

@@ -24,6 +24,7 @@ The slic (**S**tellarWP **L**ocal **I**nteractive **C**ontainers) CLI command pr
     * [Xdebug and `slic`](#xdebug-and-slic)
     * [Configuring IDEs for Xdebug](/docs/xdebug.md)
     * [Releasing a new version of `slic`](/CONTRIBUTING.md)
+* [Agent Skills (AI-assisted testing)](#agent-skills-ai-assisted-testing)
 * [Update guide](#update-guide)
   * [From 1.0 to 2.0](#from-10-to-20)
 
@@ -118,9 +119,41 @@ slic here
 
 ![slic here](docs/images/slic-here.gif)
 
-#### 2. WordPress Directory
+#### 2. Themes Directory
 
-The second option is to navigate to the root of your site (likely where `wp-config.php` lives) and run the `slic here`
+If you are developing a **theme**, run `slic here` from your themes directory. `slic` will detect that it is pointed at a themes directory and correctly:
+
+- Mount the directory as `wp-content/themes/` in the Docker stack so your theme is available to WordPress as a real theme.
+- Keep a separate plugins directory (`SLIC_PLUGINS_DIR`) so dependencies like WooCommerce install into `wp-content/plugins/` and not into your themes directory.
+- Run Codeception from within the correct `wp-content/themes/<theme>` path inside the container.
+
+Example:
+
+```bash
+# Change to your themes directory
+cd /path/to/your/wp-content/themes
+
+slic here
+slic use my-theme
+slic run wpunit
+```
+
+> **WPLoader suite config:** When testing a theme, activate it via the WPLoader `theme:` key rather than listing it under `plugins`/`activatePlugins`. WordPress will then load the theme (including its `functions.php`) automatically.
+>
+> ```yaml
+> modules:
+>   config:
+>     WPLoader:
+>       plugins:
+>         - woocommerce/woocommerce.php
+>       activatePlugins:
+>         - woocommerce/woocommerce.php
+>       theme: my-theme   # ← activates the theme under test
+> ```
+
+#### 3. WordPress Directory
+
+The third option is to navigate to the root of your site (likely where `wp-config.php` lives) and run the `slic here`
 command.
 
 > Note: This is an opinionated option and there are some assumptions that are made:
@@ -359,6 +392,42 @@ When using these commands, `slic` will prompt you to restart the containers.
 - `xon` - Enable Xdebug
 - `xoff` - Disable Xdebug
 
+## Agent Skills (AI-assisted testing)
+
+This repository includes an [Agent Skill](https://agentskills.io) in `skills/slic/` that teaches AI coding assistants (Claude Code, Cursor, Copilot, Gemini CLI, and [30+ other tools](https://agentskills.io)) how to create and run WordPress integration tests with slic.
+
+### What it provides
+
+The skill gives agents structured context about:
+
+- The slic CLI workflow (`here`, `use`, `init`, `run`, `shell`)
+- WPUnit test structure, naming conventions, and namespaces
+- `setUp()` / `tearDown()` environment tiers (minimal, standard, full isolation)
+- HTTP mocking patterns for WordPress (`pre_http_request` filter)
+- Assertion helpers and WordPress test factories
+- Advanced patterns (REST API dispatch, Reflection, custom tables)
+- An 11-item test isolation checklist for preventing flaky tests
+
+### How agents discover it
+
+Agent Skills-compatible tools discover the skill automatically when working inside this repository or any project that references it. The entry point is `skills/slic/SKILL.md`, which links to detailed sub-documents that agents load on demand.
+
+For manual installation in other projects, use the [skills CLI](https://agentskills.io):
+
+```bash
+# Install globally (available to all projects):
+npx skills add stellarwp/slic -g
+
+# Install for a specific project:
+npx skills add stellarwp/slic
+
+# Install for a specific agent:
+npx skills add stellarwp/slic --agent cursor
+
+# List available skills before installing:
+npx skills add stellarwp/slic --list
+```
+
 ## Update Guide
 
 This guide covers the steps needed when upgrading `slic` between major versions.

changelog.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+# [2.2.0] - 2026-05-29
+- Added - First-class theme support for `slic here`, `slic use`, `slic using`, and `slic run`, including auto-detection when running `slic here` from a `themes` directory with a sibling `plugins` directory.
+- Added - Agent Skills documentation in `skills/slic/` for AI-assisted WordPress integration test creation, debugging, and slic workflow guidance.
+- Added - PHP 8.4 and 8.5 Docker image support for slic and WordPress 7.0, compiling `uopz` from source for PHP 8.4+ because the PECL release does not build against PHP 8.4.
+- Changed - PHP 8.3 WordPress images now use WordPress 7.0.0.
+- Changed - Docker builds now resolve upstream official PHP and WordPress base images from Amazon ECR Public by default to avoid Docker Hub pull rate limits.
+- Fixed - Theme targets now resolve to `SLIC_THEMES_DIR` when running tests and build/install prompts instead of assuming all targets live in `SLIC_PLUGINS_DIR`.
+- Fixed - `slic run` now repairs stale or incomplete WordPress `.htaccess` rewrite blocks in the configured `SLIC_WP_DIR`, preventing Apache-level 404s for pretty REST API URLs.
+
 # [2.1.8] - 2026-03-11
 - Fixed - Add missing `igbinary` and `redis` PHP extensions to the slic and WordPress Dockerfiles.
 

containers/slic/Dockerfile

@@ -1,14 +1,16 @@
 ARG PHP_VERSION=7.4
+ARG PHP_IMAGE_REPOSITORY=public.ecr.aws/docker/library/php
 
 # Source Composer 1 and 2 from the respective images, multi-stage builds.
 FROM ghcr.io/composer/docker:1 AS composer1
 FROM ghcr.io/composer/docker:2 AS composer2
 
-FROM php:${PHP_VERSION}
+FROM ${PHP_IMAGE_REPOSITORY}:${PHP_VERSION}
 
 ARG NODE_VERSION=18.17.0
 ARG NVM_VERSION=v0.40.1
 ARG IPE_GD_WITHOUTAVIF=1
+ARG UOPZ_SOURCE_REF=14c8fc2d6eff14ec9acd926b9cab85d6961c64ac
 ARG TARGETPLATFORM
 
 SHELL ["/bin/bash", "-eou", "pipefail", "-c"]
@@ -30,12 +32,6 @@ ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/do
 
 RUN chmod a+rx /usr/local/bin/wp /usr/local/bin/install-php-extensions
 
-# -------------------------------
-# PHP extensions (heavy compilation step with cache mount)
-# -------------------------------
-RUN --mount=type=cache,target=/tmp/ipe-cache,sharing=locked \
-    install-php-extensions xdebug pdo pdo_mysql mysqli zip uopz pcntl sockets intl exif gd igbinary redis
-
 # -------------------------------
 # System dependencies (with cache mount for speed)
 # -------------------------------
@@ -52,6 +48,25 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     mkdir -p $NVM_DIR/cache /cache /composer-cache && \
     chmod a+rwx $NVM_DIR/cache /cache /composer-cache
 
+# -------------------------------
+# PHP extensions (heavy compilation step with cache mount)
+# -------------------------------
+RUN --mount=type=cache,target=/tmp/ipe-cache,sharing=locked \
+    install-php-extensions xdebug pdo pdo_mysql mysqli zip pcntl sockets intl exif gd igbinary redis && \
+    if php -r 'exit(PHP_VERSION_ID >= 80400 ? 0 : 1);'; then \
+        git clone --depth 1 https://github.com/krakjoe/uopz.git /tmp/uopz-src && \
+        cd /tmp/uopz-src && \
+        git fetch --depth 1 origin "${UOPZ_SOURCE_REF}" && \
+        git checkout --detach FETCH_HEAD && \
+        phpize && \
+        ./configure && \
+        make -j"$(nproc)" && \
+        make install && \
+        rm -rf /tmp/uopz-src; \
+    else \
+        install-php-extensions uopz; \
+    fi
+
 # -------------------------------
 # Install NVM
 # -------------------------------

containers/wordpress/Dockerfile

@@ -1,8 +1,8 @@
-ARG WORDPRESS_IMAGE_VERSION=wordpress/apache
+ARG WORDPRESS_IMAGE_REPOSITORY=public.ecr.aws/docker/library/wordpress
 ARG PHP_VERSION=7.4
 ARG WP_VERSION=6.1
 
-FROM wordpress:${WP_VERSION}-php${PHP_VERSION}-apache
+FROM ${WORDPRESS_IMAGE_REPOSITORY}:${WP_VERSION}-php${PHP_VERSION}-apache
 
 # -------------------------------
 # Environment variables

skills/slic/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: slic
+description: >-
+  Guide for creating, modifying, and running WPUnit integration tests with
+  slic (StellarWP Local Interactive Containers). Covers slic workflow, test
+  structure, environment setup, HTTP mocking, WordPress factories, assertions,
+  and Codeception/wp-browser patterns. Use when writing or debugging WordPress
+  plugin integration tests.
+license: MIT
+compatibility: Requires Docker and slic CLI on PATH
+metadata:
+  author: stellarwp
+  version: "1.0"
+---
+
+# slic — WPUnit Integration Testing Guide
+
+## When to use this skill
+
+Activate this skill when:
+
+- Writing new WPUnit integration tests for a WordPress plugin or theme
+- Modifying or debugging existing Codeception/wp-browser tests
+- Running test suites through slic (the `slic run` workflow)
+- Setting up a project for slic-based testing for the first time
+- Diagnosing flaky or order-dependent test failures
+
+## Quick-start workflow
+
+slic orchestrates Docker containers (MariaDB, Redis, WordPress, Chrome, and a Codeception runner) so you never configure a local test environment manually.
+
+### 1. Point slic at your code
+
+```bash
+# From a plugins directory (e.g. wp-content/plugins):
+slic here
+
+# Or from a full WordPress root (where wp-config.php lives):
+slic here
+```
+
+### 2. Select the target project
+
+```bash
+slic use my-plugin
+
+# Subdirectory targets are supported:
+slic use event-tickets/common
+```
+
+### 3. Initialize (first time only)
+
+```bash
+slic init my-plugin
+```
+
+This generates three files in the plugin root:
+
+| File | Purpose |
+|------|---------|
+| `.env.testing.slic` | Database credentials, WordPress URL, container paths |
+| `codeception.slic.yml` | Loads `.env.testing.slic` as Codeception params |
+| `test-config.slic.php` | Optional WPLoader custom configuration |
+
+### 4. Run tests
+
+```bash
+slic run                              # all suites, sequentially
+slic run wpunit                       # one suite
+slic run tests/wpunit/FooTest.php     # one file
+slic run tests/wpunit/FooTest::test_something  # one method
+```
+
+### 5. Interactive shell (optional)
+
+```bash
+slic shell
+# Inside the container:
+> cr wpunit                           # shorthand for codecept run
+```
+
+## Test creation rules
+
+When creating or modifying a test file, follow these rules:
+
+1. **Extend `WPTestCase`** — every WPUnit test class extends `\Codeception\TestCase\WPTestCase` (wp-browser v3) or `lucatume\WPBrowser\TestCase\WPTestCase` (wp-browser v4).
+2. **Use the AAA pattern** — Arrange, Act, Assert. Keep each section visually distinct.
+3. **Name clearly** — file: `<DescriptiveName>Test.php`; methods: `test_<what_it_verifies>` (preferred over `@test` annotations).
+4. **Isolate** — every test must pass in any order. Clean up in `tearDown()`.
+5. **Use factories** — prefer `$this->factory()->post->create()` over raw SQL or `wp_insert_post()` in test setup.
+6. **Follow WordPress coding standards** — tabs for indentation, spaces inside parentheses.
+
+See [test-anatomy.md](test-anatomy.md) for the complete file skeleton and naming rules.
+
+## Environment setup tiers
+
+Choose the right level of setUp/tearDown for your test:
+
+| Tier | When to use | Guide |
+|------|------------|-------|
+| Minimal | Tests that only need WordPress loaded | [environment-setup.md](environment-setup.md#tier-1-minimal) |
+| Standard | Tests that create posts, users, or terms | [environment-setup.md](environment-setup.md#tier-2-standard-with-factories) |
+| Full isolation | Tests that mock HTTP, change globals, or modify options | [environment-setup.md](environment-setup.md#tier-3-full-isolation) |
+
+## Testing patterns
+
+| Pattern | Guide |
+|---------|-------|
+| HTTP mocking (3 approaches) | [http-mocking.md](http-mocking.md) |
+| Assertions and WordPress factories | [assertions.md](assertions.md) |
+| REST dispatch, Reflection, custom tables | [advanced-patterns.md](advanced-patterns.md) |
+| Test isolation checklist (11 items) | [test-isolation-checklist.md](test-isolation-checklist.md) |
+
+## Verification workflow
+
+After writing or modifying tests, follow this sequence:
+
+1. **Write the code** under test (or confirm it exists).
+2. **Create or update tests** following the patterns above.
+3. **Run the targeted test** — `slic run tests/wpunit/YourTest.php`.
+4. **Run the full suite** — `slic run wpunit` — to catch side effects.
+5. **Fix any failures** and re-run.
+6. **Verify isolation** — run the single test again to confirm it passes independently.
+7. **Check the [isolation checklist](test-isolation-checklist.md)** before committing.
+
+## Reference material
+
+| Topic | File |
+|-------|------|
+| Complete slic CLI command reference | [references/slic-commands.md](references/slic-commands.md) |
+| Installation, setup, env files, CI | [references/slic-setup.md](references/slic-setup.md) |
+| WPLoader config and WPTestCase API | [references/wp-browser-wploader.md](references/wp-browser-wploader.md) |
+
+## External resources
+
+- [slic repository](https://github.com/stellarwp/slic)
+- [wp-browser documentation](https://wpbrowser.wptestkit.dev/)
+- [Codeception documentation](https://codeception.com/docs/Introduction)
+- [WordPress PHPUnit test utilities](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/)