Live E2E validation

August 2, 2026 ยท View on GitHub

The default test suite is offline. Live validation is a manual, opt-in check because DuckDuckGo may return a challenge or rate limit an automated request. The live runner never runs in npm test, npm run check, or GitHub CI.

Run

Build the package, then set the explicit confirmation variable for one command:

$env:DDG_LIVE_CONFIRM = "1"
$env:DDG_LIVE_CANDIDATE = "ddg-kit@0.1.0"
npm run live:e2e -- --query "OpenAI" --news-query "OpenAI"
Remove-Item Env:DDG_LIVE_CONFIRM
Remove-Item Env:DDG_LIVE_CANDIDATE

The runner makes one Web request and one News request. It creates a separate client for each surface, so a Web challenge does not turn the News result into an uninformative local cooldown. It does not retry either request.

Optional variables:

  • DDG_LIVE_COMMIT records the downstream or package commit under test.
  • DDG_LIVE_PROXY selects a proxy without printing its value.
  • DDG_LIVE_QUERY and DDG_LIVE_NEWS_QUERY provide query defaults.

Result classes

  • LIVE_PASS: the response contains non-empty results with valid URLs and the expected Web or News text fields.
  • LIVE_BLOCKED: the provider returns BOT_CHALLENGE or RATE_LIMITED.
  • LIVE_INCONCLUSIVE: the provider times out, returns an upstream/parse failure, or returns empty or malformed results.
  • LIVE_NOT_RUN: the explicit confirmation variable was not set.

The JSON report records counts, hostnames, field lengths, timing, error code, runtime, and candidate metadata. It does not record result URLs, VQD values, cookies, headers, or proxy credentials.

Evidence record

For a downstream migration, copy the JSON report into the corresponding canary record and include:

  1. downstream commit and installed package version;
  2. Node version, operating system, UTC timestamp, and proxy presence;
  3. separate Web and News statuses;
  4. the exact structured failure code when a request is blocked; and
  5. whether the result came from the direct client or a downstream fallback.

LIVE_PASS is provider evidence for the package client. It is not evidence of maintainer adoption. A downstream PR still requires an independent maintainer review and, where possible, a maintainer-run live check.