How to Use WordPress Playground to Test Themes and Plugins in the Browser?

You find a plugin that looks perfect for a client project, but the reviews are mixed and you have no idea how it behaves with the theme you use. The usual options are not great. Installing it on the live site is risky, spinning up a local environment takes time, and a throwaway hosting account costs money and still needs cleaning up afterwards. WordPress Playground removes that friction: it runs a complete WordPress site inside your browser tab, with no server, no database to configure, and nothing to install. You can have a fresh site with a specific theme, plugin, PHP version, and WordPress version running in a few seconds, then close the tab when you are done.

This article covers how WordPress Playground works, how to launch test sites with URL parameters, how to write Blueprints that install plugins and themes and configure the site automatically, how to save and export your work, how to use the Playground CLI to test your own code locally, and where Playground's limits are.

What Is WordPress Playground?

WordPress Playground is an official WordPress.org project that runs WordPress entirely on the client. It works by compiling PHP to WebAssembly so it can execute in the browser, and by using SQLite instead of MySQL through the SQLite Database Integration plugin. The result is a real WordPress install, with the same admin, the same Site Editor, and the same plugin and theme APIs, running without any server-side code at all.

Because everything happens in your browser:

• It is fast to start. A new site boots in seconds.
• It is disposable. Close the tab and the site is gone, unless you choose to save it.
• It is safe. Nothing you do touches a real server or a real database.
• It is shareable. A URL or a Blueprint file can recreate the exact same site for someone else.

Option	Setup time	Cost	Safe to break	Shareable setup
Testing on the live site	None	Free	No	No
Staging site on your host	Minutes	Varies	Yes	Not easily
Local Docker or wp-env	5–15 minutes	Free	Yes	Through config files
WordPress Playground	Seconds	Free	Yes	A URL or a Blueprint

Playground does not replace a staging site for testing changes against real production data, which is covered in how to set up a WordPress staging site. It is the fastest way to answer questions like "does this plugin work?" and "what does this theme look like with my content?"

Launching Your First Playground Site

Open playground.wordpress.net in any modern browser. Within a few seconds you are logged in to the admin of a fresh WordPress site running the latest version.

From there you can use WordPress exactly as you would on a server:

1. Go to Plugins → Add New Plugin, search the directory, and install a plugin.
2. Go to Appearance → Themes and install or activate a theme.
3. Create posts and pages, open the Site Editor, and change settings.

The Playground interface around the site also has a settings panel where you can choose the PHP version, the WordPress version, the site language, and whether the site has network access. Network access is what lets the site reach WordPress.org to browse and install plugins and themes.

Testing Plugins and Themes with URL Parameters

The quickest way to set up a test is the Query API: you add parameters to the Playground URL, and the site starts already configured. For example, this URL starts a site with the Gutenberg plugin installed and opens the post editor:

https://playground.wordpress.net/?plugin=gutenberg&url=/wp-admin/post-new.php

And this one starts a site with a specific theme active:

https://playground.wordpress.net/?theme=twentytwentyfive

The most useful parameters:

Parameter	What it does	Example
plugin	Installs and activates a plugin from WordPress.org by slug	?plugin=woocommerce
theme	Installs and activates a theme from WordPress.org by slug	?theme=twentytwentyfour
wp	Chooses the WordPress version (default latest)	?wp=6.8
php	Chooses the PHP version	?php=8.2
url	Sets the page to open after boot (default /wp-admin/)	?url=/wp-admin/plugins.php
login	Logs in automatically (default yes)	?login=no
language	Sets the site language	?language=fr_FR
multisite	Starts a multisite network	?multisite=yes
networking	Allows the site to make network requests (default yes)	?networking=no
mode	Changes the interface, seamless hides the Playground UI	?mode=seamless
blueprint-url	Loads a Blueprint JSON file from a URL	?blueprint-url=https://...
gutenberg-pr	Loads a Gutenberg pull request for testing	?gutenberg-pr=12345

You can repeat plugin to install several plugins at once:

https://playground.wordpress.net/?plugin=woocommerce&plugin=query-monitor&theme=storefront&php=8.3

Testing Compatibility Across Versions

Version parameters make compatibility testing straightforward. Before updating a production site to a new WordPress release, you can open two tabs side by side, one on the old version and one on the new, with the same plugins:

https://playground.wordpress.net/?wp=6.8&plugin=your-plugin-slug&url=/wp-admin/plugins.php
https://playground.wordpress.net/?wp=latest&plugin=your-plugin-slug&url=/wp-admin/plugins.php

The same approach works for PHP. If your host is about to upgrade PHP, load the site with your plugins on the new PHP version and watch for errors and warnings before your host flips the switch.

Automating Setup with Blueprints

URL parameters are fine for simple tests, but real test scenarios need more: specific options set, sample content imported, several plugins configured, a particular page open. Blueprints handle this. A Blueprint is a JSON file that describes the site you want and the steps to build it. Playground reads the file and executes the steps in order before showing you the site.

Here is a complete Blueprint that sets the PHP and WordPress versions, logs in, installs and activates a theme and two plugins, sets some site options, and opens the front end. Save it as blueprint.json:

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/",
  "preferredVersions": {
    "php": "8.3",
    "wp": "latest"
  },
  "features": {
    "networking": true
  },
  "steps": [
    {
      "step": "login",
      "username": "admin",
      "password": "password"
    },
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyfive"
      },
      "options": {
        "activate": true
      }
    },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "woocommerce"
      },
      "options": {
        "activate": true
      }
    },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "query-monitor"
      },
      "options": {
        "activate": true
      }
    },
    {
      "step": "setSiteOptions",
      "options": {
        "blogname": "Plugin Test Site",
        "blogdescription": "A disposable Playground site",
        "permalink_structure": "/%postname%/"
      }
    }
  ]
}

The key parts of a Blueprint:

• $schema points to the official JSON schema, so editors like VS Code give you autocompletion and validation.
• landingPage is the path Playground opens when setup finishes.
• preferredVersions sets the PHP and WordPress versions.
• features.networking allows the site to make outgoing requests, which installs from WordPress.org need.
• steps is an ordered list of actions. Each object names a step and passes its options.

Common Blueprint Steps

Step	Purpose
login	Logs in as a user, by default admin
installPlugin	Installs a plugin from WordPress.org, a URL, or a bundled file
installTheme	Installs a theme from WordPress.org, a URL, or a bundled file
activatePlugin	Activates a plugin that is already present
activateTheme	Activates a theme that is already present
setSiteOptions	Updates values in the wp_options table
defineWpConfigConsts	Adds constants such as WP_DEBUG to wp-config.php
importWxr	Imports content from a WordPress export (WXR) file
writeFile	Writes a file into the site's filesystem
runPHP	Runs arbitrary PHP code inside the site
wp-cli	Runs a WP-CLI command

Installing Plugins from a URL or GitHub

Not every plugin you want to test is on WordPress.org. The url resource installs a plugin or theme from any ZIP file that the browser can download:

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "url",
    "url": "https://example.com/downloads/my-plugin.zip"
  },
  "options": {
    "activate": true
  }
}

Keep in mind that the ZIP is fetched by your browser, so the server hosting it must allow cross-origin requests. GitHub release assets and raw URLs often do not, which is why the Playground docs recommend hosting test ZIPs somewhere CORS-friendly, or using a proxy for GitHub downloads.

Adding Sample Content

An empty site is a poor test of a theme. Export content from an existing site with Tools → Export, host the XML file, and import it in the Blueprint:

{
  "step": "importWxr",
  "file": {
    "resource": "url",
    "url": "https://example.com/test-content/sample-content.xml"
  }
}

The WordPress theme unit test data, published by the WordPress.org Theme Review team, is a good choice for checking how a theme handles long titles, nested comments, galleries, and edge cases in formatting.

Enabling Debugging

When you are testing a plugin, you want to see its notices and warnings. The defineWpConfigConsts step turns on debugging before WordPress loads:

{
  "step": "defineWpConfigConsts",
  "consts": {
    "WP_DEBUG": true,
    "WP_DEBUG_DISPLAY": true
  }
}

Running a Blueprint

There are two ways to load a Blueprint in the browser:

• From a URL. Host the JSON file somewhere public, for example in a GitHub repository or gist, and pass it with blueprint-url:

https://playground.wordpress.net/?blueprint-url=https://example.com/blueprint.json

• In the URL fragment. Paste the minified JSON after a # at the end of the Playground URL. This is convenient for short Blueprints and for links you share in chat, because the whole configuration travels in the link itself.

Playground also has a Blueprints gallery with ready-made examples for common scenarios, such as WooCommerce stores with products, block theme demos, and multisite setups. They are a good starting point to copy from.

Saving, Exporting, and Sharing Your Work

By default, a Playground site lives only in that browser tab. Refresh or close it and you start over. When you want to keep a site, you have several options from the Playground interface:

• Save in the browser. Playground can store a site in your browser's storage so it is still there when you return. Saved sites appear in the site manager, where you can switch between them.
• Download as a ZIP. Exports the whole site, including wp-content and the SQLite database, so you can import it into another Playground session later.
• Export to GitHub. Pushes a theme, plugin, or wp-content folder to a GitHub repository as a pull request, which is useful if you designed something in the Site Editor and want it in version control.
• Share a Blueprint. For reproducible bug reports, a Blueprint is usually better than a ZIP. It is small, readable, and anyone can open it and get exactly the same starting point.

A good pattern for bug reports to plugin authors is to write a Blueprint that installs the plugin, sets the required options, imports minimal content, and lands on the page where the bug appears. The developer clicks one link and sees the problem immediately.

Using the Playground CLI for Local Development

The browser version is great for testing published plugins and themes. When you are building your own, you want Playground to load the code from your disk so changes show up as you save. The Playground CLI does that. It requires Node.js 20.18 or later and runs through npx, so there is nothing to install globally.

The Quick Start Command

From the folder of a plugin or theme you are developing, run:

# Terminal
cd ~/projects/my-plugin
npx @wp-playground/cli@latest start

The start command detects whether the current folder is a plugin, a theme, or a whole wp-content folder, mounts it into a WordPress site, opens the browser, and keeps the site between sessions. Persistent sites are stored in your home directory under ~/.wordpress-playground/sites/. To throw the stored site away and begin fresh, add --reset.

The Server Command for Full Control

The server command gives you full control over versions, mounts, and Blueprints, which is what you want for scripts and CI:

# Terminal
npx @wp-playground/cli@latest server \
  --php=8.3 \
  --wp=latest \
  --port=9400 \
  --login \
  --mount=./my-plugin:/wordpress/wp-content/plugins/my-plugin \
  --blueprint=./blueprint.json

What the flags do:

• --php and --wp set versions. PHP defaults to 8.3 and WordPress to the latest release.
• --port sets the local port, 9400 by default.
• --login logs you in as the administrator automatically.
• --mount maps a folder on your machine into the virtual filesystem using the format /host/path:/vfs/path. Repeat it to mount several folders.
• --mount-before-install mounts a folder before WordPress is installed, which is useful when you mount an entire WordPress directory.
• --auto-mount detects the project type in the current folder and mounts it in the right place.
• --blueprint runs a Blueprint file after setup.

In server mode the site data lives in a temporary directory by default. If you want the database and uploads to persist, mount a local wp-content folder.

Running Blueprints in CI

Two more commands help with automation:

• run-blueprint executes a Blueprint without starting a web server, which is handy for checking that a plugin installs and activates cleanly.
• build-snapshot builds a ZIP snapshot of a site from a Blueprint, which you can use as a fixture for tests or demos.

A simple smoke test in a GitHub Actions workflow could look like this:

# .github/workflows/playground-smoke-test.yml
name: Playground smoke test

on: [push, pull_request]

jobs:
  smoke:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php: ["7.4", "8.3"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install and activate plugin in Playground
        run: |
          npx @wp-playground/cli@latest run-blueprint \
            --php=${{ matrix.php }} \
            --mount=./:/wordpress/wp-content/plugins/my-plugin \
            --blueprint=./tests/blueprint.json

The Blueprint in tests/blueprint.json can activate the plugin and run a runPHP step that throws an error if something is missing, so the job fails when activation breaks.

For full-time development with a real MySQL database, wp-env and Docker Compose are closer to production. See how to set up a local WordPress development environment with wp-env and how to run WordPress locally with Docker Compose.

Embedding Playground in Your Own Pages

Playground can also run inside an iframe on your own site, which plugin and theme authors use for live demos. The simplest version is an embed of the Playground URL with your parameters:

<!-- demo.html -->
<iframe
  src="https://playground.wordpress.net/?mode=seamless&plugin=your-plugin-slug&url=/wp-admin/admin.php?page=your-plugin"
  width="100%"
  height="700"
  title="Live plugin demo"
  loading="lazy"
></iframe>

The seamless mode hides the Playground interface so visitors see only the WordPress admin. For deeper integration, Playground has a JavaScript API that lets your page start a site, run Blueprint steps, and read or write files programmatically.

Limitations to Know

Playground is a real WordPress install, but it runs in an unusual environment, and some things behave differently:

• SQLite instead of MySQL. Most plugins work because they go through WordPress's database API. Plugins that write raw MySQL-specific SQL, use stored procedures, or rely on MySQL-only functions may fail.
• Limited outgoing network access. Requests go through the browser, so they are subject to CORS. Some external APIs, license servers, and payment gateways will not respond.
• No real email. wp_mail does not deliver messages to inboxes.
• No cron in the background. WP-Cron runs only when pages load, and nothing runs when the tab is closed.
• Some PHP extensions are missing. Plugins that need uncommon extensions may not activate.
• Performance differs from a server. Do not use Playground timings to judge real-world speed.
• Not for production. Playground sites are for testing, demos, and learning, not for hosting a website.

If a plugin fails in Playground, check whether it fails on a regular server before blaming the plugin. The environment may be the cause.

Common Problems and Fixes

• Plugin search in the admin shows nothing. Networking is turned off. Enable network access in the Playground settings or use ?networking=yes, and set "features": { "networking": true } in your Blueprint.
• A Blueprint fails at an install step. Check the slug on WordPress.org. The slug is the last part of the plugin's URL, not its display name.
• Installing a plugin from GitHub fails. The download is blocked by CORS. Host the ZIP on a CORS-friendly location or use a proxy.
• Changes disappear after refreshing. The site was not saved. Save it in the browser or download a ZIP before closing the tab.
• The CLI fails to start. Your Node.js version is too old. Upgrade to Node 20.18 or later.
• A plugin shows database errors. It uses MySQL-specific queries that the SQLite integration does not translate. Test it in wp-env or Docker instead.

WordPress Playground FAQ

Conclusion

WordPress Playground turns "let me try that plugin" from a half-hour job into a ten-second one. A URL with plugin, theme, wp, and php parameters covers quick compatibility checks. A Blueprint captures a complete test scenario, with content, options, and debugging, in a small JSON file you can version, share, and attach to bug reports. And the Playground CLI brings the same disposable environment to your own code and your CI pipeline.

Use Playground for evaluation, demos, learning, and reproducible bug reports. Keep a staging site or a MySQL-based local environment for anything that depends on production data, server configuration, or external services, and the two together will catch most problems before they reach your live site.

Here are some useful references for going deeper on WordPress Playground:

1. WordPress Developer Resources: WordPress Playground documentation — the official guide to Playground, Blueprints, and the APIs.
2. WordPress Developer Resources: Query API — every URL parameter with defaults and examples.
3. WordPress Developer Resources: Getting started with Blueprints — writing and loading Blueprint files.
4. WordPress Developer Resources: Playground CLI — the start, server, run-blueprint, and build-snapshot commands.
5. WordPress Playground: playground.wordpress.net — launch a site in your browser.