How to Test a Local Website with BrowserStack Screenshots
Use BrowserStack Local Testing to reach localhost, staging, and private sites from remote browsers, then capture them in Screenshots or through its API.
To test a local website with BrowserStack Screenshots, start BrowserStack Local on a machine that can reach the site, confirm the Local connection is enabled, then enter the local URL in BrowserStack Screenshots and choose the browser configurations to capture. For a local folder of HTML, CSS, and JavaScript files, enable Folder Testing and open its generated folder URL in a remote browser. For automation, establish Local Testing first and use the Screenshots API’s local option.
BrowserStack Local is useful when remote browsers cannot reach a site directly, including localhost, staging, private network sites, or sites behind a proxy, firewall, or VPN. It creates a connection from your reachable machine to BrowserStack; it does not publish your website to the public internet. BrowserStack Local Testing overview · How Local Testing works.
1. Test a running local or private website in Screenshots
- Start the site. Confirm it loads on the machine that will run BrowserStack Local. For example, a development server might be available at
http://localhost:3000. If testing a private or staging hostname, confirm that same machine can reach it. - Start BrowserStack Local. Use the BrowserStack Local app or binary and authenticate with your account’s access key as instructed by BrowserStack. Treat the access key as a secret: do not commit it, print it in public logs, or include a real key in shared commands.
- Verify the connection. Check the Local status indicator in the relevant BrowserStack interface. The Local guide describes green as enabled and red as disabled. If disabled, check the Local dashboard and its connectivity troubleshooting settings.
- Open BrowserStack Screenshots. Enter the local address, such as
http://localhost:3000, select the browser configurations you want, and generate the screenshots. The Screenshots workflow documents localhost examples includinghttp://localhostandhttp://localhost:3000.
Keep the Local process running while the remote browser loads the page. A hostname that resolves only on your machine may need special routing; see the force-local note below. See BrowserStack Screenshots and the Local setup and connectivity guide.
When to use force-local
Use the force-local setting only when routing requires it, such as restricted hostnames or local host mappings. It routes all requests through your network, which can help the remote browser resolve addresses that are meaningful only inside that network. First check the Local status and ordinary connectivity; force-local is not a general fix for a stopped server or incorrect URL.
2. Test local HTML files with Folder Testing
Folder Testing is for files in a directory, rather than a site already served at a localhost URL. Configure it with the directory’s absolute path in the Local Console or start the Local binary with its --folder flag and the absolute path, following BrowserStack’s instructions. Copy the generated local folder URL, start a BrowserStack Live session, and navigate to that generated URL in the remote browser.
Do not substitute http://localhost for the generated folder URL. Folder Testing exposes the selected directory through a BrowserStack-generated address; a running web server is a separate workflow. See BrowserStack’s local folder testing guide.
3. Automate captures with the Screenshots API
For repeatable screenshot jobs, use the Screenshots API after establishing Local Testing. Set the API’s local field for the local page and provide the URL and browser/platform settings required by the API. The API documentation describes settings for operating system, browser, device, orientation, resolution, quality, and wait time. Its availability depends on an Automate plan that includes browsers; Live-only subscribers can use the Screenshots webpage. Check the current plan and API documentation for account-specific access.
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"http://localhost:3000","local":true}' \
"https://www.browserstack.com/screenshots/api"This illustrates the local URL and local setting; add the required browser/platform fields and use the current endpoint, authentication, and request schema from the official Screenshots API documentation. Keep credentials in environment variables or a secret manager in real automation. Do not assume a request succeeds merely because the Local process is running: the API request must target the established Local connection.
4. Choose the right workflow
| Workflow | Use it for | Local access setup |
|---|---|---|
| Screenshots webpage | One-off visual checks and manually selected browser configurations | Enable Local Testing, then enter the local URL |
| Screenshots API | Repeatable or programmatically initiated screenshot jobs | Establish Local Testing and set local for the local page |
| Folder Testing with Live | A directory of local HTML, CSS, and JavaScript files | Enable folder testing, then open its generated folder URL |
This is a distinction between documented interfaces, not a performance comparison. For API access, BrowserStack says the account needs an Automate plan that includes browsers; webpage Screenshots can be used by Live-only subscribers. Confirm current plan details before making account or purchasing decisions.
5. Troubleshooting
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Local URL does not load remotely | The Local app or binary is stopped, the site is not reachable from its machine, or the Local connection is disabled. | Open the URL on the Local machine, keep the Local process running, and confirm the status indicator is enabled. |
| Local status is red or disabled | The tunnel is not active or the connection setup failed. | Review the Local dashboard and its connectivity debugging/settings; restart Local after correcting the reported setup issue. |
| A private hostname or local DNS mapping fails | The remote browser cannot resolve the hostname through the normal route. | Where the routing requires it, try force-local so requests resolve through your network. Confirm the hostname works from the Local machine. |
| Site is behind a proxy, firewall, or VPN | Organization network rules may prevent the Local connection or access to the target host. | Check BrowserStack’s current network requirements and coordinate any organization-specific proxy, firewall, or VPN settings with your network administrator. |
| Folder URL does not look like localhost | Folder Testing creates a generated BrowserStack URL for the selected directory. | Copy that URL from the Local Console and navigate to it in Live; do not enter the directory path as a website URL. |
| API capture cannot reach a local page | Local Testing was not established, or the API request omitted its local option. |
Start and verify Local first, then set local and use the API’s documented request schema. |
| API access is unavailable | The account may not have an Automate plan that includes browsers. | Check plan eligibility in the current API documentation; use the Screenshots webpage if the account is Live-only. |
6. Reliability, performance, and cost considerations
- Reachability determines success. The Local machine must be able to reach the target site, and the Local connection must remain active during capture. A tunnel cannot make an application server that is stopped or unhealthy return a page.
- Check the page from the same network context. VPN routing, proxy rules, DNS, and host mappings can change what the Local machine can see. Confirm those details before investigating browser rendering.
- Wait behavior affects captures. The API documents wait-time settings. Choose a wait appropriate to the page’s rendering needs, and avoid assuming that a screenshot taken immediately after navigation includes later asynchronous content.
- Use the right entitlement. API use requires an Automate plan that includes browsers according to the API documentation. The webpage route is available to Live-only subscribers. Plan prices and entitlements can change, so verify them in BrowserStack’s current account and plan materials.
- Protect credentials. Keep the access key out of source control, browser-visible code, and unredacted logs. Use a secret store for automated jobs and rotate credentials if they are exposed.
7. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. If you do not need remote BrowserStack browser configurations and simply want a screenshot from a URL, make one GET request. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks/CAPTCHAs, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does BrowserStack Local make my localhost site public?
No. It provides a connection so BrowserStack remote browsers can reach a site through the machine running Local; it is not public hosting.
Can I use a local folder without running a web server?
Yes. Use Folder Testing, then open the generated folder URL in a Live session. That is distinct from testing a site served at a localhost URL.
Can I use the Screenshots API with a local URL?
Yes, after Local Testing is established. Set the API’s local option and meet the documented Automate plan requirement.
Which route should I choose for one screenshot?
Use the Screenshots webpage for manual browser selection. Use the API when your workflow needs programmatic requests, and Folder Testing for local files rather than a running site.
