{"id":12134,"library":"testcafe-hammerhead","title":"TestCafe Hammerhead Proxy","description":"testcafe-hammerhead is a robust, low-level web proxy library serving as the core engine for the TestCafe end-to-end testing framework. It functions as a URL-rewriting proxy, transparently modifying URLs within proxied web pages and intercepting access to URL-containing properties to provide original values, making it appear to the client that the page is hosted at its original location. The current stable version is 31.7.7, with frequent patch and minor releases to address bugs, security vulnerabilities, and improve compatibility. Key differentiators include its ability to handle HTTP/HTTPS, WebSockets, EventSource, and file uploads, along with extensive request and response modification capabilities. It is primarily used programmatically to establish and configure proxy servers for web traffic manipulation.","status":"active","version":"31.7.7","language":"javascript","source_language":"en","source_url":"https://github.com/DevExpress/testcafe-hammerhead","tags":["javascript","typescript"],"install":[{"cmd":"npm install testcafe-hammerhead","lang":"bash","label":"npm"},{"cmd":"yarn add testcafe-hammerhead","lang":"bash","label":"yarn"},{"cmd":"pnpm add testcafe-hammerhead","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library ships with TypeScript types and favors ESM syntax. CommonJS `require` works but ESM is recommended.","wrong":"const createProxy = require('testcafe-hammerhead').createProxy;","symbol":"createProxy","correct":"import { createProxy } from 'testcafe-hammerhead';"},{"note":"Used for type hinting or explicit class instantiation, though `createProxy` is the primary factory function.","symbol":"Proxy","correct":"import { Proxy } from 'testcafe-hammerhead';"},{"note":"TypeScript interface for configuring the proxy, including port, hostname, and various handlers.","symbol":"ProxyOptions","correct":"import { ProxyOptions } from 'testcafe-hammerhead';"}],"quickstart":{"code":"import { createProxy } from 'testcafe-hammerhead';\nimport * as http from 'http';\n\n// Configure the Hammerhead proxy instance\nconst proxy = createProxy({\n  port: 8000,\n  hostname: 'localhost',\n  // Optionally, you can specify an external proxy to chain to\n  // externalProxyHost: process.env.EXTERNAL_PROXY_HOST ?? '',\n  // externalProxyPort: parseInt(process.env.EXTERNAL_PROXY_PORT ?? '8080', 10),\n});\n\n// Create a standard Node.js HTTP server\nconst server = http.createServer((req, res) => {\n  // Pass incoming requests to the Hammerhead proxy's request handler\n  proxy.onRequest(req, res);\n});\n\n// Listen on the configured port\nserver.listen(proxy.port, () => {\n  console.log(`Hammerhead proxy listening on http://${proxy.hostname}:${proxy.port}`);\n  console.log(`Try visiting a URL like: http://${proxy.hostname}:${proxy.port}/http://example.com`);\n});\n\n// You can register custom event handlers with the proxy instance\nproxy.on('request', (req, res, next) => {\n  // console.log(`Proxying request for: ${req.url}`);\n  next(); // Must call next() to continue processing the request\n});\n\nproxy.on('error', (error) => {\n  console.error('Hammerhead proxy error:', error);\n});\n\n// Graceful shutdown\nprocess.on('SIGINT', () => {\n  console.log('Shutting down Hammerhead proxy...');\n  server.close(() => {\n    console.log('HTTP server closed.');\n    proxy.close(() => {\n        console.log('Hammerhead proxy instance closed.');\n        process.exit(0);\n    });\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to create and run a basic Hammerhead URL-rewriting proxy server, listening on a specified port and hostname. It shows how to integrate it with a standard Node.js HTTP server, register event listeners, and handle graceful shutdown."},"warnings":[{"fix":"Review custom proxy handlers or plugins for reliance on the `request` package. Replace usage with Node.js built-in `http`/`https` modules or a modern alternative like `axios` or `node-fetch`.","message":"The `request` dependency was removed in v31.7.3. If your custom code or plugins implicitly relied on this package being available through TestCafe Hammerhead's internal mechanisms, you might need to update your implementations to use standard Node.js `http`/`https` modules or an alternative HTTP client.","severity":"breaking","affected_versions":">=31.7.3"},{"fix":"When debugging, consider temporarily disabling proxying if possible, or use browser developer tools that support mapping back to original sources. Be aware of this limitation when integrating with error reporting tools.","message":"Hammerhead's URL rewriting and script injection can interfere with source maps, making debugging challenging. Application runtime exceptions reported by tools like Sentry may have broken stack frames due to the modifications.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For problematic pages, investigate potential conflicts with Hammerhead's injection. Consider using TestCafe's `ClientFunction` with `dependencies` to pass necessary client-side context, or mock HTTP requests to serve 'fixed' content.","message":"Proxied pages may exhibit 'incorrect behavior' if the URL rewriting or script injection process encounters issues, particularly with complex or non-standard HTML/JavaScript. This can lead to unexpected test failures or application malfunctions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"There is no direct fix within Hammerhead for this. Consider using TestCafe's request mocking to bypass reCAPTCHA, or structure tests to avoid reCAPTCHA-protected flows if possible. Some users report success by mocking the response directly.","message":"Google reCAPTCHA v3 often fails when pages are served via the Hammerhead proxy, consistently returning a low score (e.g., 0.1). This can block logins or other functionalities on sites demanding a higher reCAPTCHA score.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your testing environment uses Node.js `>=14.0.0`. If you rely on IE for testing, TestCafe v3.0.0 and higher will no longer support it. For non-Chromium browsers or remote/cloud browsers, TestCafe still utilizes the Hammerhead proxy.","message":"As of TestCafe v3.0.0, which heavily relies on Hammerhead, native CDP automation became the default for Chromium-based browsers, and support for Internet Explorer was removed. While Hammerhead itself supports non-CDP browsers, TestCafe's default behavior may impact test environments.","severity":"breaking","affected_versions":">=3.0.0 (TestCafe)"},{"fix":"Upgrade your Node.js environment to version 14.0.0 or higher to ensure full compatibility and access to the latest features and security fixes.","message":"The minimum required Node.js version is `>=14.0.0`. Running with older Node.js versions will result in compatibility issues and potential failures.","severity":"breaking","affected_versions":"<=31.x.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Inspect the problematic JavaScript file or HTML for non-standard syntax or malformations. This issue was noted as possibly fixed in native automation versions.","cause":"Hammerhead's processing of certain JavaScript files or malformed HTML can lead to internal server errors during resource loading.","error":"Failed to load resource: the server responded with a status of 500 (Internal Server Error) TypeError: ExprGen[itemType] is not a function"},{"fix":"Ensure all URLs provided to the proxy or within proxied content are valid and correctly encoded. Verify network connectivity for external resources. This was a fix in TestCafe v3.7.4 (which bumps Hammerhead).","cause":"An incorrectly formatted or unresolvable URL was passed to a Hammerhead component responsible for base URL preparation.","error":"TypeError: Invalid URL error in prepareBaseUrl"},{"fix":"This issue was specifically addressed and fixed in Hammerhead v31.6.4. Upgrade to v31.6.4 or a later version to resolve this.","cause":"Under specific network conditions or due to internal proxy handling, socket connections could become unresponsive or terminate unexpectedly.","error":"Sockets hanging (closes #7097) / socket hang up"},{"fix":"These issues were fixed in Hammerhead v31.7.7. Ensure you are using the latest version to avoid disruptions related to web workers.","cause":"Problems with Hammerhead's handling of web module workers and their `postMessage` target URLs, leading to communication failures.","error":"Fix: issue with module workers / worker postmessage targetUrl fixed"}],"ecosystem":"npm"}