Package Information
Available Nodes
Documentation generating…
Documentation
n8n-nodes-speedtest-net
TypeScript n8n community node with its own wrapper around the official Ookla Speedtest CLI. The npm speedtest-net dependency has been removed: this package launches the installed CLI directly, captures diagnostics, and produces structured errors.
Requirements
- Self-hosted n8n and Node.js 22 or newer. Not a verified n8n Cloud node.
- No manual CLI installation is needed on Linux x64 or arm64, including n8n containers. After explicit consent, the first execution downloads the official Ookla CLI 1.2.0 over HTTPS, verifies a pinned SHA-256, and caches it for later runs. No root privileges, package manager, native npm dependencies, or install scripts are required.
- The worker needs outbound HTTPS access to
install.speedtest.netand a writable cache. The default is the visiblebinariesdirectory alongside the installed node. Administrators can setN8N_SPEEDTEST_CACHE_DIRto a writable persistent directory, particularly for read-only container filesystems. Concurrent executions share setup within a worker; files are installed atomically. - Administrators can instead set
N8N_SPEEDTEST_BINARYto an existing executable's absolute path; this bypasses downloads. Other operating systems/architectures currently require this override. Restart n8n after environment changes. - The official Linux release is musl-based. Actual execution still depends on the container's architecture and security policy (for example, executable mounts must not be
noexec). - Do not install the unrelated Python
speedtest-cli: it has different flags and output. Ookla terms and licensing still apply to the automatically downloaded binary.
Tests measure the n8n worker/container connection, not your browser. They consume bandwidth and may use significant data. Tests are sequential within one node execution, but separate workflows/workers can still overlap. One input item causes one test.
Review Ookla's EULA, Terms, and Privacy Policy. Both consent switches are disabled by default and must be explicitly enabled. Ookla's licensing restrictions apply independently of this package's MIT license.
Build and install
npm ci
npm test
npm run typecheck
npm run build
npm pack
Install the generated n8n-nodes-speedtest-net-0.2.5.tgz into your self-hosted n8n community-package directory (typically ~/.n8n/nodes) with npm, using the n8n file owner's account, then restart n8n. Install on all workers in queue mode. Each worker automatically provisions its CLI when first needed.
For local development, point N8N_CUSTOM_EXTENSIONS at the built dist/nodes directory and make the project's dependencies available alongside it. Real n8n discovery and real Ookla requests still require verification in your environment.
Usage
- Connect Manual Trigger → Speedtest.
- Review and enable both Ookla consent switches if you agree.
- Optionally choose Server ID, Source IP, or Timeout (Seconds) (default 120).
- Execute and use
{{ $json.downloadMbps }},{{ $json.uploadMbps }}, or{{ $json.ping.latency }}.
Success preserves the CLI JSON result and adds decimal downloadMbps and uploadMbps. Original bandwidth fields remain in bytes/second. All output items are linked to their input items.
Structured errors
Failures use native n8n error handling. There is no separate error-data switch:
- Stop Workflow (default): throws a node error. Structured wrapper diagnostics are preserved in the error's
context.speedtest. - Continue (using error output): failed items go to n8n's Error output with the structured JSON below. Successful items stay on the Success output.
- Continue (using regular output): explicitly keeps failed items on the regular output with the same structured JSON.
Configure this under Settings → On Error. Each continued failure contains only the error field (no copied trigger/input fields), retains its input-item link using n8n's numeric pairedItem form, and uses a JSON-only { "error": { ... } } envelope recognized by n8n's error router. Do not add a top-level execution-item error marker: n8n normalizes it to a plain message and discards the structured JSON. Object-form pairing enters n8n's automatic input-JSON merge path for error outputs; numeric pairing avoids that merge while retaining the input index. This behavior depends on the n8n engine's routing implementation and should be rechecked on n8n upgrades. Existing saved returnErrors parameters are ignored. On regular output, detect failures with {{ !!$json.error }}.
Example for the reported Ookla rate limit:
{
"error": {
"code": "RATE_LIMITED",
"message": "Limit reached: Too many requests received.",
"rateLimited": true,
"retryAfterSeconds": null,
"retryAt": null,
"retrySource": null,
"exitCode": 1
}
}
What we can and cannot know
The wrapper keeps raw stdout/stderr and termination signal internally for classification, but omits them from serialized errors. The exit code remains available when present. It can classify rate limits and recognize an explicit retry after N seconds or retry in N seconds message if the CLI emits one. This is parsed CLI text, not an HTTP header or a documented promise from Ookla.
A direct CLI wrapper cannot expose hidden HTTP response headers. If Ookla does not print a retry duration, it remains null. retryAt is currently always null; a log timestamp is never treated as a quota reset. No fabricated cooldown, automatic retries, or rate-limit bypass is implemented. A rate-limit/licensing error can require more than simply waiting.
Error codes include RATE_LIMITED, TIMEOUT, BINARY_NOT_FOUND, BINARY_SETUP_ERROR, UNSUPPORTED_PLATFORM, SPAWN_ERROR, CLI_ERROR, INVALID_RESULT, OUTPUT_LIMIT, and INVALID_CONFIGURATION. Initial binary setup has a separate 60-second download timeout and a 16 MiB archive limit; the configured test timeout starts after setup.
Timeout and output-limit failures kill the direct child and wait for process termination before returning. Captured stdout/stderr is limited to 1 MiB total. Diagnostics can contain network addresses or other sensitive information: restrict access to execution data and avoid publishing raw logs.
Tests and layout
nodes/Speedtest/Speedtest.node.ts: n8n UI and per-item integration.nodes/Speedtest/runSpeedtest.ts: shell-free CLI execution, timeout, output bounds, and result conversion.nodes/Speedtest/resolveBinary.ts: automatic official CLI provisioning, SHA-256 verification, safe extraction, and executable caching.nodes/Speedtest/speedtestError.ts: structured diagnostics and rate-limit classification.tests/: mocked process tests, n8n integration unit tests, and local fixture-process tests; no real Ookla requests.
Tests do not prove deployment compatibility or verify a real Ookla quota reset. The package is MIT licensed; see LICENSE.