How to Test a Local PWA on a Physical Phone

Why test a local PWA on a physical phone?

A Progressive Web App is a web application that can use browser and operating-system capabilities beyond an ordinary page. Depending on the browser, operating system, application, and permission state, it may register a service worker, cache resources, launch from the Home Screen or app launcher, use a standalone display mode, or receive push messages. These behaviors involve the actual mobile browser, network stack, storage policy, permission model, and installation surface.

Responsive mode in desktop developer tools can reveal layout breakpoints, viewport mistakes, and touch-target problems. It does not turn the desktop browser into the phone’s browser or reproduce every operating-system integration. It cannot fully validate the real installation flow, standalone-window behavior, physical keyboard behavior, safe-area insets, mobile storage constraints, background suspension, notification delivery, or the experience of returning to an installed app after the operating system has removed it from memory.

Testing through localhost introduces another important distinction. On your development computer, localhost refers to that computer. On a phone, it refers to the phone. If browser-facing code points to http://localhost:3000, opening the application on a phone does not redirect that request to your workstation. The browser attempts to reach port 3000 on the phone itself.

A private LAN address can make a development server reachable when both devices share a network, but plain HTTP on a LAN does not necessarily behave like a secure production origin. Service workers and many powerful browser capabilities are generally restricted to secure contexts, subject to browser-specific exceptions and policies. Browsers commonly grant special local-development treatment to loopback addresses on the same computer, so success on desktop localhost does not prove that an HTTP LAN address will behave the same way on a phone.

With Localtonet, our client runs on a device that can reach your development server and establishes an outbound connection to a Localtonet relay. An HTTP tunnel points to the PWA’s local IP address and port 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 open the assigned origin over Wi-Fi or mobile data while the selected client is connected, the tunnel is running, and the local PWA process is available.

Physical phone
Android browser or iPhone Safari
        |
        | HTTPS request to the assigned public origin
        v
Public Localtonet HTTPS address
        |
        v
Localtonet relay
        ^
        | Outbound client connection
        |
Connected Localtonet client
        |
        | Local IP address and port
        v
Local PWA target
For example: loopback or another client-reachable host + your actual app port

Prerequisites and supported inspection combinations

Begin with a locally runnable PWA and a physical phone. The development machine must be able to start the application. 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 identify specific client devices and must not appear in screenshots, source code, test logs, browser recordings, or shared bug reports.

Know the exact command your project uses to build and start. There is no universal PWA startup command because projects use different frameworks, package managers, output directories, and preview servers. Use your project’s documented command and verify its output before adding the tunnel. Some development environments disable production service workers or change caching behavior to reduce stale-development problems, so use a production-like build when evaluating installation, offline behavior, and updates.

The application must also implement the capabilities under test. For manifest checks, it needs a linked web app manifest. For service-worker and offline checks, it needs a service worker with the intended fetch, caching, or fallback behavior. For Web Push, it needs a browser-supported subscription flow, application backend, delivery path, and notification handling. The tunnel cannot supply missing PWA logic.

Choose the desktop and phone combination

Android remote inspection normally requires Developer options and USB debugging. Enabling Developer options varies by device manufacturer, but it commonly involves opening the phone’s build-number entry in system settings and tapping it repeatedly until developer features are enabled. Then enable USB debugging under Developer options. Use a trusted development computer, and revoke debugging authorizations when they are no longer needed.

For iPhone Safari, use a Mac with a current Safari version. Connect the phone with a data-capable cable for the most predictable initial setup, unlock it, and accept the trust prompt if shown. On the iPhone, enable Web Inspector under Safari’s advanced settings. Depending on the iOS release, Safari settings may appear directly under Settings → Safari or under Settings → Apps → Safari. On the Mac, enable Safari’s developer features so the Develop menu or equivalent developer interface is available. Apple’s current workflow is documented in the Safari Web Inspector instructions for iOS.

Record the test environment

Record the phone model, operating-system version, browser and version, whether the application ran in a browser tab or installed mode, the public origin, the build identifier, and the initial storage state. Platform behavior changes over time, so a result from one device should not be generalized to every browser or operating-system release.

Define the required scenarios before testing. A useful plan separates a fresh browser visit, fresh installation, repeat launch with warm caches, upgrade from an older worker, offline launch, offline deep link, network recovery, and denied permission. This prevents every result from being collected in 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 runs 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 worker or manifest already fails locally, an HTTPS origin may change secure-context behavior, but it will not repair incorrect files or application logic.

Check worker paths and scope

Service worker scope is controlled by the worker script location, registration options, response headers, and browser rules. A worker registered from a root-level path can generally control a broader part of the origin than one placed in a nested directory. Confirm that every page intended to use the worker falls within the reported scope.

Avoid hardcoding a development hostname into registration paths or cache keys unless that is intentional. Root-relative URLs such as /manifest.webmanifest and /sw.js follow the current origin, while absolute URLs remain tied to their encoded scheme and host. The right approach depends on whether the frontend and API share an origin.

Check proxy-sensitive behavior

Through a public origin, the externally visible scheme and host differ from the local upstream address. Some frameworks need carefully scoped trusted-proxy or public-origin configuration to generate correct absolute URLs and secure cookies. Do not enable broad proxy trust without understanding its security effect. Inspect redirects, links, cookie behavior, canonical URLs, and callbacks through the public address.

Tunneling the frontend does not automatically expose a separate local API. Browser requests execute on the phone. An API call to localhost targets the phone, while a private LAN address may be unreachable over mobile data. Use a phone-reachable API origin appropriate to the application and configure cross-origin, cookie, and authentication policies deliberately.

Create a Localtonet HTTP tunnel for the PWA

After the PWA works locally, use an HTTP tunnel to publish the web service. HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, and each serves the configured content at a public HTTPS address. Use the process type available and appropriate for your test. Server choices and option availability can vary, so select current values from the dashboard instead of copying a hardcoded server code.

The sequence below summarizes the product workflow. You can also consult the official Localtonet HTTP tunnel documentation when checking the current dashboard interface.

The tunnel is available only while the selected client is connected and the tunnel is running. If the PWA process stops, requests can reach the tunnel edge but cannot be completed by the local target. If the client disconnects or the tunnel stops, the public test path becomes unavailable.

Test service worker registration, scope, and lifecycle

Once the phone loads the PWA through HTTPS, test the worker as a lifecycle rather than checking only whether registration resolved. A registered worker can still have the wrong scope, fail installation, remain waiting, serve stale files, or never control the current document.

Registration and control

Start with a defined clean state and load the public URL. Confirm that the worker script returns successfully and that registration produces no console error. Then determine whether the page is controlled. A first visit can register a worker without immediately placing the current page under its control. A later navigation or reload may be necessary, depending on the lifecycle and application code.

Inspect the active worker’s script URL and scope. Navigate to a route inside the intended scope and, if the design limits coverage, another route outside it. This detects workers placed too deeply in the URL hierarchy or registered with an unexpected scope.

Install and activate behavior

During installation, verify that intended application-shell resources enter the correct cache. A worker can fail if a required precache request fails. Inspect network failures and cache contents instead of assuming that a visible registration means installation completed.

During activation, check whether obsolete cache versions are removed according to the application’s policy. Deleting every unfamiliar cache can interfere with other components on the same origin, while never deleting old caches wastes storage and preserves obsolete responses. Cleanup must match the application’s cache naming and deployment design.

Fetch handling and data safety

Test static assets, navigation documents, images, API responses, authenticated data, and real-time information separately. These resources do not necessarily belong under the same caching strategy.

Install the PWA and test standalone and offline behavior

Open the manifest through the public origin and verify that the browser can fetch and parse it. Check names, icons, start URL, scope, display behavior, and theme information against the application’s intent. Installation requirements and browser UI vary by platform and release. A browser may use manifest information without presenting the same installation prompt or criteria as another browser.

Do not use the presence or absence of a service worker as a universal installation verdict. A worker remains central to service-worker-based offline behavior, push handling, and other worker features, but current installation eligibility is defined by each browser. Consult the current browser-focused PWA installation guidance and validate the exact browser under test.

Install on Android

Google documents the current user-facing process in its Chrome web app installation instructions. Treat those instructions as version-sensitive because menu labels and the distinction between installation and a shortcut can change.

Add the PWA to the Home Screen on iPhone

Apple maintains the current procedure in its iPhone guide for adding a website to the Home Screen. Safari does not need to present a Chromium-style automatic install prompt for the Home Screen flow to be available.

Test authentication and callbacks

Confirm that login does not redirect to an unreachable localhost address, lose session state, or strand the user in an unintended browser window. OAuth and other identity systems may require the exact public HTTPS callback origin to be registered. Do not weaken callback validation to accommodate a temporary URL. Register only the intended test callback, use non-sensitive accounts, and remove temporary entries afterward.

Run the offline sequence

Include a cold offline deep-link test. Cache the content your design promises 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 worker does not provide the correct document fallback.

Reset installed-app and site state for repeatable tests

Removing a Home Screen icon does not always clear the origin’s cookies, Cache Storage, IndexedDB, worker registration, permissions, or other website data. Conversely, clearing browser data may not remove every installed launcher entry. For a reproducible clean-install test, remove the installed PWA and clear the tested origin’s site data.

Reset an Android Chrome test

Google’s Chrome browsing-data documentation describes current data-clearing controls. Prefer a per-site reset when you need to preserve unrelated browser state.

Reset an iPhone Safari and Home Screen test

Validate updates and Web Push behavior

Service worker and cache updates

An update test requires origin continuity. Install or visit an old build through one public HTTPS address, keep that address, modify the application, and serve the new build through the existing tunnel. Changing the hostname creates a new origin and converts 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 worker or assets using the project’s normal build process, then revisit the app. Observe whether the browser detects a new worker, whether it installs and waits, and when it activates. Some applications let the old worker continue until controlled windows close. Others present a reload notice or implement an earlier activation policy.

Judge the update by consistency, not just speed. The active document, scripts, styles, and caches must belong to compatible versions. A new document paired with obsolete assets, or an old document referencing removed assets, can break the application. Test with one tab, multiple tabs, a backgrounded installed app, and a return after the device has been idle.

If the application announces an update, verify that the notice appears at the intended time and does not create an endless reload loop. Test while a form contains unsaved work if updates could interrupt user activity. Cache cleanup should follow the application’s versioning policy.

Web Push prerequisites

Web Push requires more than HTTPS. It depends on browser and operating-system support, notification permission, a service worker, application-side subscription handling, a push service, backend delivery, and notification interaction logic. Some platforms and versions may require an installed Home Screen web app or other conditions. Test the exact target browser and operating-system release.

Request notification permission in response to an appropriate user action and explain why notifications are useful. Test grant, denial, and dismissal. After denial, the application should remain usable and should not repeatedly pressure the user. The tunnel does not alter the browser’s permission decision.

Where supported, confirm that the subscription reaches the backend and is associated with the correct test account. Test delivery while the app is visible, backgrounded, and closed. Verify notification content and tap behavior. A notification link pointing to localhost, an obsolete hostname, or a route outside the intended scope can fail even if delivery succeeds.

Remotely inspect Android Chrome and iPhone Safari

Inspect Android Chrome with chrome://inspect

Google maintains the current procedure in its Chrome DevTools remote-debugging documentation. Desktop and phone Chrome versions that are far apart can cause inspection problems, so update them or follow Google’s compatibility guidance if the device appears but a debugging session does not open.

Inspect iPhone Safari from a Mac

If the iPhone does not appear, confirm that both devices are unlocked, the cable supports data, the trust relationship is established, Web Inspector is enabled, and Safari developer features are enabled. Managed-device policy can also restrict inspection.

Capture useful evidence

Reproduce the issue with a visible build identifier and record the public origin, route, initial storage state, worker status, device model, operating system, browser version, installed or tab mode, and relevant errors. Do not include Localtonet tokens, session credentials, authorization headers, push subscription secrets, private API payloads, or customer data.

Troubleshoot the public URL

If the public URL does not load, verify that the PWA still loads locally. Confirm that the Localtonet client is connected, the correct device was selected, the HTTP tunnel is started, and the local IP address and port match the running server. A configuration can exist without running, and a running tunnel cannot serve an upstream process that has stopped.

If the client runs on another device, confirm that it can reach the configured target. A server bound only to loopback is available to a client on the same machine but not automatically to another machine. Changing the bind address can increase LAN exposure, so make that choice deliberately and apply appropriate firewall rules.

Troubleshoot assets, workers, installation, and login

When the document loads but assets fail, inspect the requested URLs. Absolute paths may still reference localhost, a LAN address, an old hostname, or plain HTTP. Mixed-content rules can block insecure resources from an HTTPS page. Correct the browser-facing origins rather than disabling browser security.

If the worker does not register, verify secure-context status, the worker response, redirects, authentication interception, script syntax, requested scope, and browser support in the current mode. If it registers but does not control the page, compare the document URL with the reported scope, inspect active and waiting workers, and account for the first-load lifecycle.

If installation is not offered, validate the manifest, icon responses, start URL, scope, display configuration, HTTPS origin, console, prior dismissal state, and whether the app is already installed. Then check the exact browser’s current installation model. Safari’s Add to Home Screen path should not be judged by the presence of a Chromium-style prompt.

If login or redirects fail, inspect whether the application generates URLs from its local upstream host rather than the public origin. Review cookie domain, path, Secure, and SameSite behavior. Confirm that the identity provider recognizes the exact HTTPS callback and that browser-facing configuration no longer points to localhost.

Operate the test safely and tear it down cleanly

Expose only the local web port needed for the PWA, not a database, inspector, administration service, or unrelated port. Keep test accounts separate from production accounts and use non-sensitive data. Privileged routes must retain their own authentication and authorization because possession of a tunnel URL is not authorization.

Before sharing the address, open it 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, sample credentials, and development utilities. A local development server can contain conveniences that are inappropriate on a public origin.

When testing is complete, stop the Localtonet tunnel. Delete it if the configuration is no longer needed. Stop the local application and client when appropriate. Creating, starting, stopping, and deleting a tunnel are distinct lifecycle actions.

Remove temporary accounts, callback registrations, and push subscriptions created only for the test. On a shared phone, uninstall the PWA and clear the origin’s site data, caches, permissions, and stored credentials. Revoke Android USB debugging access or disconnect the iPhone trust relationship when required by your device-management policy.

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

Frequently asked questions