WordPress 7.1 ships the first runnable examples in the Code Reference using WordPress Playground. The official examples are a useful model, but teams copying the pattern into internal docs should verify iframe origin, cookies, storage, parent-page access, network requests, package loading, reset behavior, and what code or output survives between runs.
Use this when developers, agencies, training teams, or plugin vendors want runnable WordPress examples in documentation, support portals, onboarding material, or internal code labs.
Quick answer
Open an official runnable example in a clean browser profile and record the iframe origin, sandbox attributes, storage, cookies, service workers, network requests, console output, and reset result. Run marked code that changes only the isolated Playground site, then reload and start a second example. Confirm it cannot read the parent site's authenticated data, private storage, or unrelated tabs, and document any permitted network or persistence behavior before adopting the pattern elsewhere.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Parent access | Marked DOM and cookie | Unavailable to child |
| Network | Unapproved endpoint | Blocked or documented |
| Reset | Created option and file | Isolated state cleared |
| Second tab | Different example | No unintended shared state |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Capture the official boundary | Record WordPress and browser versions, example URL, iframe source and origin, sandbox attributes, permissions policy, cookies, storage keys, workers, and network destinations. | Runnable code cannot read or modify the parent page's cookies, storage, DOM, or authenticated session. |
| Run harmless marked state tests | Run harmless marked code that creates an option, transient, post, file, outbound request attempt, console line, and PHP error inside the example environment. | Network, worker, package, clipboard, popup, and download behavior matches the written policy. |
| Test browser privacy modes | Test reset, reload, back and forward, a second example, two tabs, private browsing, blocked third-party cookies, strict tracking protection, and offline mode. | Reset and reload produce the documented state boundary across tabs and browser modes. |
| Document network and persistence | Inspect whether the child can access parent DOM, parent cookies, parent storage, authenticated requests, clipboard, downloads, popups, or unexpected external endpoints. | A custom documentation embed is tested independently rather than assumed equivalent to WordPress.org. |
What to check first
- Record WordPress and browser versions, example URL, iframe source and origin, sandbox attributes, permissions policy, cookies, storage keys, workers, and network destinations.
- Run harmless marked code that creates an option, transient, post, file, outbound request attempt, console line, and PHP error inside the example environment.
- Test reset, reload, back and forward, a second example, two tabs, private browsing, blocked third-party cookies, strict tracking protection, and offline mode.
- Inspect whether the child can access parent DOM, parent cookies, parent storage, authenticated requests, clipboard, downloads, popups, or unexpected external endpoints.
- Separate the security properties of the official Code Reference implementation from any custom documentation host that changes headers, origins, iframe attributes, or asset sources.
Field notes
- Write the pass condition before changing anything. A repeatable synthetic fixture makes the before and after comparison useful.
- Keep exact versions and UTC timestamps because scheduled jobs, caches, retries, and background processing can change the evidence.
- Check the public experience and the stored server-side result. Admin previews and isolated API calls do not prove the whole workflow.
- Repeat the test after the relevant cache, queue, scheduled action, webhook, and observation window has finished.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
isolation_fixture:
parent_marker: WAVE82-PARENT
child_option: wave82_playground_test
outbound_target: https://invalid.example/test
expected_parent_access: false
expected_reset_persistence: false
record_network_requests: true
Why this usually happens
- A custom embed removes iframe sandbox attributes used by the official implementation.
- The Playground origin or service worker scope is broader than the documentation team expects.
- Browser privacy settings change storage or third-party cookie behavior.
- A code example imports a remote dependency or sends output to an external endpoint.
Decision rule
Adopt runnable examples only when the child cannot reach parent authenticated state, all network destinations are intentional, reset behavior is clear, and custom hosting preserves the tested isolation controls.
Production verification checklist
- Runnable code cannot read or modify the parent page's cookies, storage, DOM, or authenticated session.
- Network, worker, package, clipboard, popup, and download behavior matches the written policy.
- Reset and reload produce the documented state boundary across tabs and browser modes.
- A custom documentation embed is tested independently rather than assumed equivalent to WordPress.org.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Capture the official boundary
- Run harmless marked state tests
- Test browser privacy modes
- Document network and persistence
- Retest custom embeds separately
Mistakes to avoid
- Changing production before recording exact versions, UTC time, the affected fixture, current behavior, and a tested rollback point.
- Accepting one successful admin screen while the stored record, API response, queue, email, browser, or downstream system remains unchecked.
- Testing only as an administrator instead of the role, browser, locale, network state, catalog size, and failure path a real user reaches.
- Leaving broad credentials, debug logs, temporary filters, synthetic records, or recovery code active after verification.
Questions teams ask during testing
Should I test this on production?
Use production for read-only evidence first. Reproduce the change on staging with current data, extensions, cache, browser mix, and integration settings. If a production canary is necessary, make it reversible, identifiable, monitored, and unable to charge a customer or expose personal data.
How do I rule out a cache artifact?
Record the origin response, purge only affected paths, and repeat in private and normal sessions. Compare stored data and server logs with the visible page. A cache hit is useful evidence only when you know which version and settings it contains.
What belongs in the evidence packet?
Keep UTC time, exact versions, fixture ID, role, browser, expected result, actual result, relevant response or log lines, change made, rollback point, owner, and final verification. Redact passwords, tokens, personal data, and private URLs.
When is the test complete?
Close it when the main path and important failure branches pass, records reconcile across systems, accessibility and mobile checks are complete, temporary changes are removed, and monitoring covers the next update or business cycle.
What to tell the client or owner
Give the owner a short packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key evidence, change made, rollback point, unresolved risk, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP review a WordPress code lab.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references