How to Test a WordPress Theme Locally Before Going Live

Choosing a local environment: LocalWP vs wp-env vs plain Docker

LocalWP (by WP Engine) is the simplest option for most people: install the desktop app, click "Create a new site," and you have a working WordPress install with MySQL and PHP configured in under a minute, no terminal required. It is the best default choice if you mainly need a quick, disposable environment to test theme uploads and activation.

wp-env, WordPress's official command-line tool, spins up a Docker-based environment defined by a .wp-env.json file, which is better if you want a reproducible, version-controlled setup you can share with a team or run in CI. Plain Docker Compose with the official wordpress and mysql images gives you the most control but requires writing your own configuration.

Setting up wp-env for theme development

wp-env requires Node.js and Docker installed. It is particularly convenient for testing a single theme repeatedly during active development, since it mounts your local theme folder directly into the container so file changes are reflected immediately without re-uploading.

1. Install Docker Desktop and Node.js if not already installed.
2. Run npm -g install @wordpress/env to install wp-env globally.
3. From your theme's project folder, create a .wp-env.json file specifying "themes": ["."] to mount the current folder as a theme.
4. Run wp-env start to build and launch the containers.
5. Visit http://localhost:8888 for the site and http://localhost:8888/wp-admin for the admin dashboard (default admin/password).

Installing and activating the theme locally

Whichever environment you choose, the workflow is the same: log into wp-admin, go to Appearance → Themes → Add New → Upload Theme, and select your zip, or place the unzipped folder directly into wp-content/themes/ if you have file system access, which is faster for iterative development since you skip re-zipping on every change.

Enabling debug settings for accurate testing

Before testing, edit wp-config.php in your local install to enable full error visibility: define('WP_DEBUG', true);, define('WP_DEBUG_LOG', true);, and define('WP_DEBUG_DISPLAY', true); since it is a local, non-public environment where showing errors on screen is safe and convenient. This surfaces PHP notices and warnings that a production environment with debugging off would hide entirely.

• WP_DEBUG — turns on PHP error reporting for WordPress core, theme, and plugin code
• WP_DEBUG_LOG — writes all errors to wp-content/debug.log for later review
• WP_DEBUG_DISPLAY — shows errors directly on the page, fine locally, risky on live sites
• SCRIPT_DEBUG — set true to load unminified core JS/CSS for easier debugging

Running the Theme Check plugin

Install the Theme Check plugin (available on WordPress.org, install via Plugins → Add New in your local site) and run it against your theme from the Themes menu. It checks for required files, deprecated functions, missing text domains, inline styles that should be enqueued, and other WordPress.org submission-level standards, flagging issues well before a client or the community would notice them.

Even if you never plan to submit the theme to the official directory, treating its checklist as a quality bar catches real bugs, not just style nitpicks, particularly around escaping output and correctly enqueuing scripts.

What to manually verify beyond automated checks

Automated tools do not catch visual regressions or animation issues, so manually click through every page template, test on a narrow mobile viewport in devtools' responsive mode, and compare against the original design pixel-for-pixel where fidelity matters. If the theme originated from a live site conversion, testing locally is exactly where you would catch a missing animation script or a broken enqueue order, discussed in our CSS animation preservation guide, before it reaches production.