How to Test a Local PWA on a Physical Phone

Why test a local PWA on a physical phone?

A Progressive Web App is still a web application, but its behavior can extend beyond an ordinary browser tab. Depending on the browser and operating system, it may register a service worker, cache resources, launch from the Home Screen or app launcher, use a standalone display mode, receive push messages, and respond differently when it is backgrounded or resumed. Those behaviors involve the mobile browser, operating system, network state, storage policies, permission model, and installation surface.

Responsive mode in desktop developer tools can help detect layout breakpoints, touch-target problems, and viewport mistakes. It does not turn the desktop browser into the phone’s browser or reproduce every operating-system integration. A desktop simulation cannot fully validate the real installation flow, standalone window behavior, permission prompts, physical keyboard behavior, safe-area insets, mobile storage constraints, background suspension, or notification delivery on a locked device.

Testing through localhost on the development computer also hides an important networking distinction. On your computer, localhost refers to that computer. On a phone, localhost refers to the phone itself. If the PWA or any browser-facing configuration points to http://localhost:3000, the phone will not reinterpret it as the development machine. It will try to reach port 3000 on the phone.

A LAN address can make a development server reachable when the phone and computer share a network, but a plain HTTP LAN origin does not necessarily behave like a secure production origin. Service workers and other powerful browser capabilities are generally restricted to secure contexts, subject to browser-specific exceptions and policies. Browsers often treat local development on the same computer specially, so successful behavior on desktop localhost does not prove that the equivalent HTTP address on a phone will work.

With Localtonet, the client running on the device that can reach your development server establishes an outbound connection to our relay. An HTTP tunnel points to the local IP address and port of the PWA and provides a public HTTPS address. This avoids inbound router port forwarding, firewall changes, VPN setup, and the need for a public IP address. The phone can then open the assigned HTTPS origin over Wi-Fi or mobile data while the selected Localtonet client is connected and the tunnel is running.

Prerequisites and test planning

Begin with a locally runnable PWA and a physical phone. The development machine must be able to start the application, and the Localtonet client must run on that machine or another device that can reach the application’s local IP address and port. You also need a Localtonet device token associated with the client. Tokens are device-specific credentials and must not be placed in screenshots, source code, test logs, or shared bug reports.

The application itself should include whatever features you intend to test. For installation and service worker checks, that normally means a linked web app manifest and a service worker registration. For offline testing, the service worker must implement the intended caching or fallback behavior. For Web Push testing, the application also needs its own push subscription and delivery implementation. The tunnel cannot supply missing application logic.

Know the exact command your project uses to build and start. This guide cannot provide a universal command because PWA projects use different frameworks, package managers, output directories, and development or production servers. Use the command defined by your project and confirm its output before involving Localtonet. Do not assume that a framework’s development server behaves like its production build. Some development environments disable service workers, replace them with development workers, or change caching to prevent stale assets.

Record the test environment

For repeatable results, record the phone model, operating-system version, browser and browser version, whether the app was tested in a tab or installed mode, the public origin, the build identifier, and the initial storage state. Platform support changes over time, so a result from one device should not be generalized to every browser.

Define which scenarios matter before testing. A useful plan separates a fresh visit, a fresh installation, a repeat launch with warm caches, an upgrade from an older worker, an offline launch, an offline deep link, a network recovery, and a denied permission. This avoids the common mistake of running every test with one already-warmed browser profile.

Verify the PWA locally before creating a tunnel

A tunnel should not be the first diagnostic step. Verify that the application is running correctly on the development machine and identify the exact target IP address and port. If the local server is unavailable, Localtonet has nothing to forward to. If the service worker or manifest is already failing locally, an HTTPS origin may change secure-context behavior, but it will not repair incorrect files or application logic.

Check service worker paths and scope

Service worker scope is controlled by the worker script location, registration options, response behavior, and browser rules. A worker registered from a root-level path can usually control a broader portion of the origin than one located in a nested directory, but the exact intended scope belongs to your application design. Confirm that the pages you plan to test fall within the worker’s reported scope.

Avoid hardcoding a development hostname into service worker registration or cache keys unless that is deliberate. Root-relative URLs such as /manifest.webmanifest or /sw.js naturally follow the current origin, while absolute URLs remain tied to the host encoded in them. Whether relative or absolute URLs are appropriate depends on your architecture, especially when the API and frontend use different origins.

Check proxy-sensitive application behavior

When an application is served through a public origin, its externally visible scheme and host differ from its local upstream address. Some frameworks need trusted-proxy or public-origin configuration to generate correct absolute URLs and secure cookies. The correct setting is framework-specific, so do not enable broad proxy trust without understanding its security effect. Instead, inspect redirects, generated links, cookie behavior, and callback URLs through the public address.

If the frontend calls a separate local API, tunneling only the frontend does not automatically expose that API. Browser requests execute on the phone. A request to an API on localhost therefore targets the phone, while a private LAN address may be unreachable over mobile data. Use a phone-reachable API origin appropriate to your architecture, then configure cross-origin and authentication policies deliberately. Do not disable security controls simply to make a test pass.

Create a Localtonet HTTP tunnel for the PWA

After the PWA works locally, use an HTTP tunnel to publish the local web service. HTTP and File Server tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, and each serves content at a public HTTPS address. For this workflow, use the process type available and appropriate for your account and test. Exact server choices and option availability can vary, so obtain current values from the dashboard rather than copying a hardcoded region or server code.

The public tunnel remains available only while the selected client is connected and the tunnel is running. If the PWA process stops, requests may still reach the tunnel edge but cannot be completed by the local target. If the Localtonet client disconnects or the tunnel is stopped, the assigned address will no longer provide the running test path.

Test service worker registration, scope, and lifecycle

Once the phone can load the PWA through HTTPS, test the worker as a lifecycle rather than checking only whether registration returned successfully. A registered worker may still have the wrong scope, fail during installation, remain waiting indefinitely, serve stale files, or never control the current page.

Registration and control

Start with a clean state and load the public HTTPS URL. Confirm that the service worker script is requested successfully and that registration does not produce a console error. Then determine whether the page is controlled. The first page load can register a worker without immediately placing that same page under its control, depending on the lifecycle and application code. A navigation or reload may be required.

Inspect the active worker’s script URL and scope. Make sure the scope covers the routes that need offline or fetch behavior. Navigate to a route inside the intended scope and another outside it, if your design intentionally limits coverage. This helps detect a worker that was placed too deeply in the URL hierarchy or registered with an unexpected scope.

Install and activate behavior

During installation, verify that the intended application-shell resources are cached. A worker can enter a redundant or failed state if one required precache request fails. Inspect failed network requests and cache contents rather than assuming that the presence of a registration means installation completed.

During activation, check whether obsolete cache versions are removed according to your application’s policy. Deleting every unknown cache can interfere with other application components on the same origin, while never removing old caches can waste storage and preserve obsolete responses. The correct cleanup behavior must match your cache naming and deployment design.

Fetch handling and cache strategy

Test different resource classes separately. Static build assets, navigation documents, images, API responses, user-specific data, and real-time information do not necessarily belong under the same caching strategy. Verify actual behavior instead of assuming a framework default is correct.

Test the manifest, installation, standalone launch, and offline behavior

Open the manifest through the public origin and verify that the browser can fetch and parse it. Check that its names, icons, start URL, scope, display behavior, theme information, and other fields match your application’s intent. Exact installability criteria and user-interface wording vary by browser and can change over time. A valid manifest and active service worker are important signals, but no single tunnel-level result guarantees that a browser will display an install prompt.

Installation checklist

Use the installation mechanism presented by the target browser. Some browsers display an install prompt, some expose installation in a menu, and some use an operating-system sharing or Home Screen flow. Record what the actual browser offers rather than requiring one platform’s wording on another.

After installation, leave the browser and launch the PWA from the Home Screen or app launcher. Confirm that it opens the intended start URL, uses the expected icon and name, and appears in the intended display mode. Test internal navigation, back behavior, external links, file or camera interactions used by your app, keyboard-open layouts, rotation, safe areas, backgrounding, and resume.

Authentication deserves a separate pass. Confirm that login does not unexpectedly strand the user in another browser window, redirect to an unreachable localhost address, or lose session state when returning to standalone mode. OAuth and other identity systems may require the public callback origin to be registered in their own configuration. Never weaken callback validation merely to accommodate a temporary tunnel URL.

Offline test sequence

Also test a cold offline deep link. First cache the content your design expects to support, fully close the app, remain offline, and open a direct route. Single-page applications often pass in-app navigation tests but fail direct navigation because the server or service worker does not provide the correct document fallback.

Validate cache updates and Web Push behavior

Service worker and cache updates

An update test requires origin continuity. Install or visit the old build through one public HTTPS address, keep that same address, modify the application, and then serve the new build behind the existing tunnel. Changing to another public hostname creates a new origin and turns the exercise into a fresh-install test.

Make an observable but safe change, such as displaying a build identifier in a diagnostic area. Update the service worker or assets using your project’s normal build process, then revisit the app. Observe whether the browser detects the new worker, whether it installs and waits, and when it becomes active. Applications choose different policies: some allow the old worker to continue until every controlled tab closes, while others ask the user to reload or activate an update sooner.

Do not judge the policy only by update speed. Verify consistency. The active document, JavaScript bundles, styles, and cached data should belong to compatible versions. A new document paired with obsolete assets, or an old document referencing removed assets, can produce a broken interface. Test with one tab, multiple tabs, a backgrounded installed app, and a return after the device has been idle.

If your application announces an update, verify that the notice appears at the intended time, remains understandable, and does not cause an endless reload loop. If user work can be lost, test an update while a form or unsaved operation is active. Cache cleanup should happen according to the application’s versioning rules, not merely because a new build exists.

Web Push prerequisites

Web Push is more than an HTTPS page. It depends on support in the target browser and operating system, notification permission, a service worker, a valid application-side subscription flow, a push service, and server-side delivery. Some platforms may require the PWA to be installed before offering the relevant capability. Current behavior must be checked on the exact browser and OS version under test.

Ask for notification permission in response to an appropriate user action and explain the value first. Test grant, denial, and dismissal. After a denial, the app should remain usable and should not repeatedly pressure the user. The tunnel does not alter or override the browser’s permission decision.

When support is available, verify that the subscription reaches your application backend, survives or expires according to platform behavior, and is associated with the correct test user. Send a test message and check delivery while the PWA is visible, backgrounded, and closed. Lock-screen behavior depends on device notification settings and operating-system policies.

Inspect notification content and interaction. Confirm the intended title, body, icon, and other supported fields. Tap the notification and verify that it focuses an existing app window or opens the correct phone-reachable HTTPS route, according to your implementation. A notification link that points to localhost, an obsolete tunnel hostname, or a route outside the worker’s intended scope can fail even though delivery succeeds.

Remote debugging and troubleshooting

Use the phone’s browser debugging facilities when available. Remote debugging setup differs by operating system, browser, desktop platform, cable or network connection, and current browser version, so follow the current browser vendor workflow for the exact device combination. Once connected, inspect the console, Network panel, Application or Storage tools, service worker registrations, manifest, Cache Storage, IndexedDB, cookies, and permission state.

Reproduce the problem with a visible build identifier and capture the public origin, route, test state, service worker status, device details, and relevant errors. Do not include Localtonet tokens, session credentials, push subscription secrets, private API payloads, or customer data in a bug report.

The public URL does not load

Confirm that the PWA still loads directly on the development machine. Then verify that the Localtonet client is connected, the correct device token was selected, the HTTP tunnel is started, and the local IP address and port match the active server. A tunnel configuration can exist without running, and a running tunnel cannot serve an upstream process that has stopped.

If the client runs on another device, test whether that device can reach the configured target. A service bound only to loopback is reachable from a client on the same machine but not automatically from another machine. Adjusting a server’s bind address changes its exposure on the local network, so make that choice deliberately and apply host firewall rules appropriate to the environment.

The document loads but assets fail

Inspect failing asset URLs. Absolute URLs may still reference localhost, a LAN address, an old public hostname, or plain HTTP. Root-relative paths should remain on the current origin, while relative paths can behave differently under nested routes. Also inspect redirects and generated canonical or base URLs.

Mixed-content restrictions can block insecure subresources from an HTTPS page. Update browser-facing resource and API URLs to secure, reachable origins rather than disabling browser security. If the PWA depends on another service, that service needs its own appropriate reachability and security design.

The service worker does not register

Check whether the browser considers the page a secure context, whether the worker script returns a successful JavaScript response, and whether redirects or authentication intercept the worker URL. Confirm that the script has no syntax or evaluation error and that its requested scope is permitted. Also verify that the browser supports service workers in the current mode. Private browsing modes may apply different storage or service worker policies.

The service worker registers but does not control the page

Compare the page URL with the reported service worker scope. Determine whether this is the first load before control has been established. Reload or navigate only after inspecting the lifecycle so that a reload does not hide the original problem. Check for an older registration controlling the page and for multiple registrations with overlapping or unexpected scopes.

The PWA is not offered for installation

Validate the manifest fetch and parsed fields, icons, start URL, scope, display configuration, service worker status, HTTPS origin, and browser console. Then check the current installability rules and installation UI for the exact browser. Some browsers do not expose a Chromium-style automatic prompt, and prior dismissal or an existing installation can affect what appears.

Offline mode shows a blank page

Determine which request failed first. The HTML shell may be cached while a required JavaScript file is missing, or the interface may collapse when an API request rejects. Verify Cache Storage entries and test uncached data explicitly. Provide a deliberate offline state for dynamic content rather than assuming every request can be satisfied.

An old version remains active

Inspect active, waiting, and installing workers. Close other tabs and installed-app windows if your update policy waits for existing clients to disappear. Confirm that the worker script or imported scripts actually changed and are served as expected. Review cache versioning and cleanup. Avoid repeatedly clearing all storage as the only fix because that conceals the upgrade path real users will experience.

Login, cookies, or redirects fail through the tunnel

Check whether the application generates URLs from the local upstream host instead of the public origin. Inspect cookie domain, path, secure, and same-site behavior. Verify that the identity provider recognizes the exact HTTPS callback URL and that browser-facing runtime configuration no longer points at localhost. Use framework-specific trusted-proxy settings carefully rather than accepting forwarded values from every source without review.

Web Push permission or delivery fails

Separate the stages. First verify API availability. Then inspect permission state, service worker readiness, subscription creation, backend registration, send response, device notification settings, delivery, and click handling. A failure at one stage does not identify the others. Reset permissions only through supported browser or operating-system controls, and document the state before changing it.

Operate the test safely and tear it down cleanly

Use the narrowest test surface possible. Expose only the local web port needed for the PWA, not a database, development inspector, administration service, or unrelated port. Keep test accounts separate from production accounts and use non-sensitive data. Ensure that privileged routes retain their own authentication and authorization because possession of the tunnel URL should not be treated as authorization.

Before sharing the public address with another tester, check the page in a signed-out browser and verify what an unauthenticated visitor can access. Remove verbose error pages and secrets from client-side configuration. Review source maps, diagnostics, test endpoints, and sample credentials. A development server can contain conveniences that are inappropriate on a public origin.

When the session is complete, stop the Localtonet tunnel. If the test configuration is no longer needed, delete it. Stop the local application and the client when appropriate. Remember that creating a tunnel, starting it, stopping it, and deleting it are distinct lifecycle actions.

Clear temporary test accounts and invalidate any subscriptions or callback entries created solely for the test. If you tested Web Push, remove obsolete subscriptions from the application backend where your implementation supports that operation. If the phone is shared, uninstall the PWA and clear its site data, caches, permissions, and stored credentials using the controls available on that platform.

Preserve only sanitized evidence: build identifier, device model, OS version, browser version, expected result, actual result, and non-sensitive console or network details. Never preserve a device AuthToken, session cookie, authorization header, private endpoint, or real customer payload in a ticket.

Frequently asked questions