{"id":20878,"date":"2026-10-27T07:17:00","date_gmt":"2026-10-27T06:17:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20878"},"modified":"2026-10-25T22:34:28","modified_gmt":"2026-10-25T21:34:28","slug":"wordpress-playground-blueprints-for-plugin-previews-and-tests","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/wordpress-plugins-tricks\/tutorials-en-wordpress-plugins-tricks\/wordpress-playground-blueprints-for-plugin-previews-and-tests\/","title":{"rendered":"WordPress Playground: Blueprints for plugin previews and tests"},"content":{"rendered":"
The Preview button on a WordPress.org plugin page opens a temporary test site in the browser. PHP and the database run through WebAssembly. A file called a Blueprint describes setup, including the PHP version, required plugins and demo values. The same file can serve the directory preview, local Playground runs and the Playground part of automated tests.<\/p>\n
The example adds a small demonstration plugin to Contact Form 7. A second test path uses Docker and wp-env<\/code>. That path has a separate .wp-env.json<\/code> and does not execute the Blueprint. The difference is visible: the Blueprint sets an option to 14, while activation without the Blueprint sets 30. This article separates those paths and states exactly what the tests check. Original runtime evidence dates from 29 September 2026; the schema, sources and isolated checks were reviewed again on 25 October 2026.<\/p>\n
Playground, Blueprints and the steps that matter<\/h2>\n
In the browser, Playground needs no separate PHP web server. PHP runs as WebAssembly, and the database uses SQLite. The command-line version uses that runtime under Node.js. The V1 Blueprint shown here is a JSON file: landingPage<\/code> selects the first page, preferredVersions<\/code> contains php<\/code> and wp<\/code>, and steps<\/code> lists setup actions in order. The example enables features.networking<\/code> explicitly. $schema<\/code> points to the rules an editor can use to validate the file.<\/p>\n
Supported versions depend on the Playground release. The current schema accepts PHP 7.4 and 8.0 through 8.5, among others, plus latest<\/code> and next<\/code>; special legacy entries also exist. Concrete combinations matter more for this example than a supposedly permanent complete list. The matrix therefore names WordPress 6.7.9, 7.0.6 and 7.1.2. These are selected test versions, not a claim about the latest release today.<\/p>\n
Three steps prepare this example:<\/p>\n
\n
installPlugin<\/code> takes a pluginData<\/code> resource, for example {\"resource\": \"wordpress.org\/plugins\", \"slug\": \"contact-form-7\"}<\/code>, a url<\/code> pointing to a ZIP file, or a git:directory<\/code> reference. Activation is controlled by options.activate<\/code>, which belongs inside options<\/code> and not inside pluginData<\/code>. In the source code, a missing activate<\/code> counts as true.<\/li>\n
login<\/code> needs only username<\/code>, defaulting to admin<\/code>. The password<\/code> field is marked deprecated in the schema.<\/li>\n
setSiteOptions<\/code> stores the values from options<\/code> as WordPress options. The example sets the site title and demo value 14.<\/li>\n<\/ul>\n
Other steps can execute PHP, install language packs or set values in wp-config.php<\/code>. Older examples contain pluginZipFile<\/code> and phpExtensionBundles<\/code>; the current schema marks these as deprecated or unused. Dependency order is written explicitly in steps<\/code>. A publicly reachable Blueprint can open through ?blueprint-url=<\/code>; a JSON fragment after https:\/\/playground.wordpress.net\/#<\/code> is another option. The diagram separates the shared Playground Blueprint from the independent Docker configuration.<\/p>\n\n\nThe Blueprint serves the preview, local Playground runs and Playground CI. Docker separately uses .wp-env.json and the example\u2019s default 30 rather than demo value 14.<\/figcaption>\n<\/figure>\n
The Blueprint for the directory preview<\/h2>\n
A public preview requires a valid file at assets\/blueprints\/blueprint.json<\/code> in the SVN directory. A committer, meaning an account allowed to write to that plugin repository, must also set the preview to \u201cpublic\u201d under Advanced. Before that, Test Preview is visible only to those accounts. An automatically generated test Blueprint can provide a starting point.<\/p>\n
The inspected importer accepts matching Blueprint files from this folder up to 102,400 bytes each and retains at most ten. Normal previews use blueprint.json<\/code>. Invalid JSON is discarded. For this example plugin, the importer appends installation of the plugin\u2019s own slug if no matching step exists, and forces activation. Matching ZIP URLs on downloads.wordpress.org<\/code> are rewritten as slug resources. A version specified in the filename can therefore be lost. Import does not simply pass the file through unchanged.<\/p>\n
The Blueprint therefore installs Contact Form 7 and sets demo values, but does not download the add-on itself. The directory appends that download. The local Playground CLI instead mounts the working folder and activates the add-on after the Blueprint steps. A separate download step could fail for an unpublished plugin or replace the mounted working folder through the default overwrite<\/code> option. The Docker path independently uses its own plugin list.<\/p>\n
In this Git project, the file is stored at .wordpress-org\/blueprints\/blueprint.json<\/code>. That folder name is a convention of the example. The release process then copies the file to assets\/blueprints\/<\/code> in SVN. A leading dot does not automatically exclude a folder from a plugin ZIP; the packaging process must actually apply that exclusion.<\/p>\nJSON<\/span>
![\"The](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/playground-reviewed-20878-en-20261025.png\")
\n