You fix the content script, rebuild, click Reload on the extension card, and repeat the failing action. Same bug. The website tab still contains the script injected before your fix. Chrome has accepted the new extension files; that open page has not received them. One browser session can contain two generations of your code, turning a missed page refresh into an afternoon of debugging a function you already repaired.
To install a Chrome extension in developer mode, open chrome://extensions in desktop Chrome, enable Developer mode, click Load unpacked, and select the folder containing manifest.json. Extract ZIP downloads first. Chrome’s installation instructions document those steps. The extension card confirms installation, not that your latest source reached the browser. Before testing behavior, establish three facts: which directory Chrome loaded, which build wrote there, and which open pages need fresh content scripts.
Load the folder your build actually writes
A plain JavaScript extension can load directly from its source directory. TypeScript and bundled projects need generated JavaScript. Read the repository’s package scripts and setup instructions, run its build command, and locate the resulting extension directory. Names such as dist and build are conventions, not Chrome requirements. If the repository contains several manifests, selecting the first one you find can load a template or a different browser target instead of the artifact you meant to test.
Open the output directory and check the manifest’s file references against its contents. If background.service_worker names worker.js, that file must exist at the specified path relative to the extension root. Check popup HTML and declared content scripts the same way. A missing generated file is a build or packaging failure; editing the message handler will not fix it. Record the build command, output path, and source revision together so a tester can identify and recreate the artifact.
Rebuild, reload the extension, then refresh the page
For a page integration, use this order: finish the build, reload the extension at chrome://extensions, then refresh the target website tab. The extension reload applies manifest and worker changes; refreshing the website replaces content scripts already injected into that page. After rebuilding popup assets, close and reopen the popup to create a new document. These are separate lifetimes. Clicking the website’s refresh button alone does not apply a changed manifest or replace the extension’s worker registration.
Check the build’s exit status before starting that sequence. A compiler failure can leave yesterday’s output in place, allowing Chrome to reload files that look valid but contain none of your edits. Display a build identifier in the popup during development and change it for each artifact handed to a tester. A report that names build 42 while you expect build 43 exposes a stale-artifact problem before anyone starts tracing application logic.
Trace the action through the console that owns it
A popup, a service worker, and a content script do not share one console. Inspect the popup to catch its rendering and click-handler failures. Open the worker’s inspection link on the extension card for background handlers. Inspect the website for content-script failures, selecting the extension’s execution context when evaluating its variables. Chrome’s extension debugging guide shows these entry points. An empty popup console says nothing about whether the worker received its message.
For a Save button, trace one action across the boundaries: popup click, outgoing message, receiving handler, network response, and result rendered on the page. Attach the same diagnostic request ID to those events. If the receiving handler never logs that ID, investigate message delivery before changing the API call. If the request succeeds but the page stays unchanged, inspect the reply and its consumer. Log event names and status codes, excluding credentials and page contents. Our Manifest V3 extension patterns cover these implementation boundaries.
Close the debugger and test the next event
Inspecting an extension service worker keeps it active. That changes the condition you need to test: Chrome normally terminates idle extension workers, discarding their global variables. Close the worker’s DevTools, wait until the extension card reports it inactive, then trigger the next action without reopening the inspector first. The service worker lifecycle documentation describes this shutdown behavior. Passing with an attached debugger does not prove that a fresh worker can handle the same event.
Take a worker that assigns selectedWorkspace after login and keeps it only in a global variable. Saving a record works immediately. After shutdown, the next Save event starts a worker with no selected workspace. Persist that selection in appropriate extension storage and read it before handling the save. Test both the restored selection and the missing-selection path. Opening the popup is insufficient: repeat the operation that consumes the state, and verify that the record reaches the expected workspace.
Hand over an artifact and an acceptance task
Give the tester a named build, installation steps, a specified test page, and the account conditions required for one acceptance task. For example: save one record from that page and confirm it appears once in the selected workspace. Request the build identifier, failing step, and observed result in bug reports. An empty-popup screenshot cannot distinguish a rendering exception from expired authentication or the wrong package. Written reproduction steps let the next developer repeat the failure without waiting for another reply.
Run those instructions in a separate Chrome profile using the exact artifact you will send. Start without your development profile’s extension storage or existing login session. Confirm installation, first-use setup, the acceptance task, and the same task after worker shutdown. Our file handoff checks apply here: inspect the package the recipient gets. For Chrome extension development, completion means another person can identify the build, install it, and reproduce the expected result with the debugger closed.
Questions, answered.
How do I install a Chrome extension in developer mode?
Open chrome://extensions in desktop Chrome, enable Developer mode, and click Load unpacked. Select the extension folder containing manifest.json. If you received a ZIP, extract it before selecting the folder.
Which folder should I select for Load unpacked?
Select the directory containing the installable manifest.json and its referenced files. For a TypeScript or bundled project, run the documented build command and select its generated extension directory. A manifest template in the repository root is not proof that the root is installable.
Why are my Chrome extension changes not showing?
Check that the build succeeded and wrote to the directory Chrome loaded. A failed build can leave old output intact. Reload the extension, then refresh the affected website tab to replace its injected content scripts. Close and reopen the popup to load rebuilt popup assets.
Why does my Chrome extension only work with DevTools open?
Inspecting the service worker keeps it active, which can hide state stored only in global variables. Close the inspector, wait for the worker to become inactive, and repeat the failing action. Persist required state in appropriate extension storage and read it when the next event arrives.
How do I debug an unpacked Chrome extension?
Inspect the popup for popup errors, use the worker’s inspection link on chrome://extensions for background errors, and open the target page’s DevTools for content-script errors. Trace one action from its outgoing message through the receiving handler and response, using a shared diagnostic request ID.