WordPress 7.1 introduces a persistent toolbar across supported editor screens. A plugin item that worked on a full page load may disappear during client-side navigation, keep a stale URL, duplicate itself after several route changes, or expose an action to the wrong role. Keyboard focus can also return to an unexpected place when the toolbar remains mounted while the main editor view changes.
Use this for plugins and themes that add admin-bar nodes, open modals, launch support tools, show environment badges, or link between the front end, Block Editor, and Site Editor.
Quick answer
Create a matrix for administrator, editor, author, and a custom role. Start from the front end, posts list, Block Editor, Site Editor, and a direct deep link. Navigate with clicks, browser Back and Forward, keyboard, command palette, and a fresh reload. Count each toolbar node, inspect its URL and capability check, activate its action, then confirm focus and active state after every route transition. Register the item through supported WordPress hooks, bind client-side behavior once, and remove stale listeners when an editor view unmounts.
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 |
|---|
| Full reload | Block Editor deep link | One allowed item with current URL |
| Client route | Editor to Site Editor | No duplicate node or listener |
| Restricted role | Author account | Protected action absent or denied |
| Keyboard | Tab, Enter, Escape, Back | Predictable focus and history |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Map nodes, capabilities, and lifecycle | Inventory every toolbar node, callback, capability, nonce, target URL, script handle, event listener, and screen condition. | Every supported screen shows exactly one intended item. |
| Reproduce every navigation path | Test full reloads and client-side transitions between the front end, post editor, Site Editor, list screens, and direct deep links. | Restricted roles cannot reveal or execute protected actions. |
| Bind client behavior once | Repeat the path for administrator, editor, author, custom role, multisite site admin, and super admin where relevant. | Back, Forward, direct load, keyboard, and client-side navigation pass. |
| Authorize the server action | Check keyboard focus, Escape handling, accessible name, tooltip, active state, browser history, and reduced-motion behavior. | DOM counts, requests, console, and PHP logs stay clean after repeated transitions. |
What to check first
- Inventory every toolbar node, callback, capability, nonce, target URL, script handle, event listener, and screen condition.
- Test full reloads and client-side transitions between the front end, post editor, Site Editor, list screens, and direct deep links.
- Repeat the path for administrator, editor, author, custom role, multisite site admin, and super admin where relevant.
- Check keyboard focus, Escape handling, accessible name, tooltip, active state, browser history, and reduced-motion behavior.
- Watch the DOM, console, network panel, and PHP log for duplicate nodes, duplicate handlers, stale nonces, and failed requests.
Field notes
- Write the expected result before changing anything and keep one repeatable synthetic fixture for the full test window.
- Record exact versions and UTC timestamps because caches, retries, scheduled actions, and deployments can change the evidence between checks.
- Test the public path and the stored server-side result, not only an admin preview, isolated command, or API response.
- Review the result again after the relevant cache, queue, cron, webhook, and observation window has completed.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
add_action( 'admin_bar_menu', function ( $bar ) {
if ( ! current_user_can( 'edit_posts' ) ) return;
$bar->add_node( [ 'id' => 'site-audit', 'title' => 'Site audit', 'href' => admin_url( 'tools.php?page=site-audit' ) ] );
}, 80 );
# Test full loads and client-side routes with each owned role.
Why this usually happens
- A script assumes every editor navigation performs a complete document load.
- The same listener is attached after each route event without removing the prior handler.
- Visibility is decided in JavaScript while authorization is missing from the server callback.
- A cached nonce or screen ID remains attached to a toolbar item after the route changes.
Decision rule
Ship only when each role sees one correct toolbar item, the destination and nonce stay current, keyboard focus remains predictable, and repeated route changes do not add DOM nodes, listeners, requests, or console errors.
Production verification checklist
- Every supported screen shows exactly one intended item.
- Restricted roles cannot reveal or execute protected actions.
- Back, Forward, direct load, keyboard, and client-side navigation pass.
- DOM counts, requests, console, and PHP logs stay clean after repeated transitions.
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.
- Map nodes, capabilities, and lifecycle
- Reproduce every navigation path
- Bind client behavior once
- Authorize the server action
- Verify focus, history, and logs
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, a stable fixture, the expected result, and a tested rollback point.
- Treating one successful screen as proof while logs, stored records, background jobs, caches, emails, APIs, and downstream systems remain unchecked.
- Testing only as an administrator instead of using the role, device, locale, cache state, request path, and failure branch that users actually reach.
- Leaving debug output, temporary exclusions, helper accounts, duplicate hooks, broad permissions, or relaxed firewall rules active after verification.
Questions teams ask during testing
Can I test this directly in production?
Start with read-only evidence. Use staging for code, package, security, checkout, form, privacy, or cache changes. If a production canary is necessary, make it identifiable, reversible, monitored, and incapable of exposing personal data or charging a customer.
How do I avoid a false positive?
Repeat the same fixture with the same versions, URL, role, locale, cache state, and downstream integration. Compare the public result, stored result, and logs instead of relying on one browser view.
What evidence should I retain?
Keep UTC time, exact versions, request or record ID, expected result, actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact credentials, tokens, and personal data.
When is the work complete?
Close it when the primary path passes, failure branches are understood, stored and downstream records reconcile, temporary changes are removed, monitoring is active, and the owner has the evidence packet.
What to tell the client or owner
Give the owner a concise packet with the affected workflow, exact versions, UTC test time, synthetic fixture ID, expected result, actual result, key logs, change made, rollback point, final result, unresolved risks, 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 test a WordPress 7.1 admin integration.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Profile the toolbar after repeated client navigation
After the visible menu and role checks pass, run the WordPress 7.1 persistent toolbar memory leak profile to measure retained editor stores, detached modal nodes, listeners, observers, timers, and repeated requests across a fixed route loop.
Helpful references