Free tools Windows power users keep installed
One-click scans. No signup required.
To test how an application handles a screenshot API failure, intercept the request and choose the failure that matches the behavior you want: return HTTP 500 or 503 for a server-error response, or abort the request for a transport-level failure. These are different cases. A 503 is a valid HTTP response; an aborted request has no HTTP response. Test the branch your application actually handles.
Choose the failure your test needs
First decide what the client is supposed to experience. A controlled HTTP error tests how it handles a server response. An aborted request tests what happens when the browser cannot obtain any response. Mixing these cases can leave an important error path untested.
| Case | How to inject it | What to verify |
|---|---|---|
| Screenshot service returns an error | Fulfill the intercepted request with status 500 or 503 and, if useful, an error body. | The application displays its server-error state, ends loading, and offers the retry behavior its contract specifies. |
| Connection or transport fails | Abort the intercepted request, or take the browser context offline. | The application displays its network-error path and does not report a successful screenshot. |
| A page resource fails | Abort the specific resource request, or use a provider option that fails rendering for a matching resource. | The application or rendering job handles missing critical page data as intended. |
| Provider rejects the request | In a controlled test account, send invalid input or omit/change credentials. | The client handles the provider’s documented validation or authentication response without exposing secrets. |
| Provider rate-limits a request | Use a safe test quota or provider sandbox if available. | Backoff and user messaging follow the documented contract. |
Mock an HTTP 500 or 503 in Playwright
Playwright can intercept network traffic and either modify a response or abort a request. For a screenshot API call, register the route before the action that triggers the call—such as navigating to the page or clicking a capture button—so the request cannot escape the test before interception begins.
import { test, expect } from '@playwright/test';
test('shows a recoverable error when screenshot API returns 503', async ({ page }) => {
await page.route('**/v1/shot**', async route => {
await route.fulfill({
status: 503,
contentType: 'application/json',
body: JSON.stringify({ error: 'Temporarily unavailable' }),
});
});
await page.goto('http://localhost:3000');
await page.getByRole('button', { name: 'Capture screenshot' }).click();
await expect(page.getByRole('alert')).toContainText(/unavailable|try again/i);
await expect(page.getByRole('progressbar')).toHaveCount(0);
await page.screenshot({ path: 'screenshot-error-state.png' });
});Replace the local page address, route pattern, button label, and expected alert with the ones used by your application. Keep the matching pattern narrow enough to catch the API request without intercepting unrelated traffic.
#1 Best Overall
The test checks observable behavior, not merely that the mock ran: the page communicates an error, stops showing progress, and records the error state if that screenshot is part of your regression workflow. Add assertions for retry controls or telemetry only where they are part of your product’s actual contract.
Test recovery by removing the mock and retrying
A retry test should make the initial failure deterministic and then allow a later request through. Remove the route handler before the retry, or replace it with a handler that returns a success-shaped response appropriate to your client. The essential sequence is: inject the failure, assert the error UI, remove the fault, retry, and assert that the UI reaches its success state. Do not assert success just because the retry button was clicked.
Test a transport-level failure
Use route.abort() when the browser should receive no HTTP response. This exercises a different client path from a 500 or 503 response.
test('shows a network error when screenshot request is interrupted', async ({ page }) => {
await page.route('**/v1/shot**', route => route.abort());
await page.goto('http://localhost:3000');
await page.getByRole('button', { name: 'Capture screenshot' }).click();
await expect(page.getByRole('alert')).toContainText(/network|connection|failed/i);
await expect(page.getByRole('progressbar')).toHaveCount(0);
});You can also take the browser context offline to exercise broader offline behavior, but that may disrupt page loading and other requests as well as the screenshot API. Aborting only the API route isolates the fault and generally makes the test easier to interpret.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsUnderstand HTTP errors versus failed requests
Playwright’s Page API documentation distinguishes an HTTP error response from a request failure: a 404 or 503 is still a successful response from the HTTP standpoint. A request is considered failed when the client cannot obtain an HTTP response, as with a network error. See the Playwright Page API and its Mock APIs guide.
That difference matters when application code branches on a returned status, catches a thrown network exception, or listens for a failed-request event. A status mock tests the former; an aborted request tests the latter. Assert against the user-visible contract as well as any status or event your application explicitly consumes.
Fail a hosted screenshot render on page-resource errors
Sometimes the failure to test is not the screenshot API call itself, but a required resource inside the page being rendered. Provider controls can make the render fail when selected resources fail.
ScreenshotOne: fail on a matching resource error
ScreenshotOne documents fail_if_request_failed. When enabled for a matching resource URL, it forces the rendering request to fail if that resource encounters a browser or network error or returns an HTTP status from 400 through 599. Use a narrow URL match for the resource your test depends on; an incidental image or analytics call should not invalidate a capture you otherwise want to test. Consult the ScreenshotOne errors documentation for the current parameter behavior.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteApiFlash: fail on selected statuses or ranges
ApiFlash documents fail_on_status, which accepts comma-separated statuses or hyphen-separated ranges. Its example includes 400,404,500-511. This is useful when a particular HTTP response from the rendered page should fail the API call rather than produce a screenshot. Check the ApiFlash documentation for current syntax and behavior before relying on it in a test.
Exercise provider-side API errors safely
Provider validation, authentication, quota, and rendering errors are distinct from browser-page errors. A separate Screenshot API reference lists common examples such as 400 for invalid requests, 401 for missing or invalid credentials, 429 for rate limits, and 502 for render failures. Those codes are vendor-specific examples, not a universal contract; consult the current documentation for the provider you use before writing assertions.
Rank #3
- Invalid request: Send deliberately malformed input in a test account and verify that the client reports a useful validation failure.
- Authentication: Use a controlled test credential or omit it in an isolated environment. Never place a live secret in test logs or screenshots.
- Rate limiting: Prefer a sandbox or safe test quota. Avoid generating production traffic merely to trigger a limit.
- Render failure: Distinguish an API response indicating a provider-side rendering problem from a request that never reached the provider.
Because providers differ in status codes, response bodies, and retry guidance, make contract tests assert only behavior documented for the provider and plan in use. The reference for the examples above is Screenshot API documentation.
Build a reliable failure-test matrix
A compact suite should cover the faults that your application promises to handle rather than every imaginable outage. Keep one test per distinct failure mechanism so failures have a clear diagnosis.
- HTTP server error: Fulfill the screenshot endpoint with 500 or 503; verify error UI, cleared loading state, and retry contract.
- Transport error: Abort the endpoint; verify the network-error path and no false success.
- Critical page resource: Fail only the resource that matters; verify the render or application handles incomplete data correctly.
- Validation or authentication: Use controlled invalid input or credentials; verify a safe, actionable error.
- Rate limit: Use a test quota or sandbox; verify documented backoff and messaging.
- Recovery: Remove the fault and retry; verify the app can transition out of its error state.
At each stage, look for four user-facing invariants: no endless spinner, a truthful error rather than a success state, retry behavior consistent with the product contract, and no leaked credentials. Playwright’s official mock-API guide demonstrates intercepting a response, reloading to verify the error UI, capturing that state, removing the mock, and retrying.
Troubleshooting test failures
The API call escapes before the mock applies
Register page.route() before navigation or before the user action that sends the request. Confirm that the route pattern matches the actual URL, including path and query-string variations.
The test expects a request failure for status 503
A 503 is an HTTP response, not a transport failure. Use route.fulfill({ status: 503 }) to test status handling; use route.abort() to test the no-response path.
The page stays on a spinner
Check that the application handles both rejected network requests and non-success HTTP statuses. Some HTTP client libraries resolve a response for 4xx/5xx while others expose an error branch; write the test for your client’s behavior and the app’s own contract.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →An incidental resource makes the render fail
Narrow the Playwright route pattern or provider URL match to the required request. Broad failure rules can turn optional images, trackers, or unrelated assets into false test failures.
The retry test keeps failing after the first error
Make the fault’s lifecycle explicit. Remove the interception or configure the next request separately, then verify that the retry actually reaches the success path. Avoid a permanent mock that fails every retry unless repeated failure is the scenario under test.
A provider status assertion breaks after an API change
Check the provider’s current documentation and your account’s plan-specific behavior. Status codes and response formats are provider contracts, not interchangeable conventions across services.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance and reliability considerations
Route interception makes tests deterministic because the failure does not depend on a real outage, but it cannot by itself prove how a live provider behaves under load. Keep mocked error-path tests in the fast application suite; use a separate, controlled integration test if you need to validate credentials, quotas, or a provider’s actual error contract.
Avoid inducing rate limits or repeated render failures against production credentials. Use sandbox facilities where available, keep secrets out of test artifacts, and constrain fault injection to test traffic. For page-resource failure tests, target only resources whose absence should matter to the capture; this reduces brittle failures from optional third-party content.
Or skip the browser setup
For a real capture rather than a mocked failure-path test, ScreenshotNeo provides a screenshot API and MCP server. A request returns an image or PDF; its response headers identify the page verdict and whether the request was billed. Clean shots remove cookie/consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are not billed, and cache hits cost nothing. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for AI agents.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does Playwright treat a 503 as requestfailed?
No. A 503 is an HTTP response; a request failure means the client did not obtain an HTTP response.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Should I use a live outage to test my error screen?
No. Intercept and control the request in a test so the failure is repeatable and isolated.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
