test(firecrawl): add unit tests for firecrawl client functions by solodmd · Pull Request #97714 · openclaw/openclaw

solodmd · 2026-06-29T07:50:42Z

What Problem This Solves

The firecrawl-client.ts module provides URL safety validation, search-item extraction, and scrape payload parsing for the Firecrawl web tools plugin. However, this module lacked unit tests to verify the client behavior, which could lead to regressions when the functions are modified.

Why This Change Was Made

Add unit tests for assertFirecrawlScrapeTargetAllowed, resolveSearchItems, and parseFirecrawlScrapePayload to verify client behavior including URL validation, multi-shape search response extraction, scrape payload parsing, and truncation boundaries. This improves test coverage and prevents regressions.

The module already exported these functions through its testing object, confirming they were intended for direct unit coverage.

Focused tests cover:

assertFirecrawlScrapeTargetAllowed: valid public URLs, invalid strings, non-HTTP protocols, private/loopback IPv4/IPv6, blocked hostnames, embedded credentials, missing scheme
resolveSearchItems: all 6 candidate-array paths, empty/missing payloads, non-object entries, URL/title/description/content/published field fallbacks, metadata precedence, empty-string edge cases
parseFirecrawlScrapePayload: markdown/content fallback, no-content throws, text vs markdown mode, metadata enrichment, truncation boundaries (exact, 1-over, zero), warning field handling, type safety

User Impact

No user-visible change. The Firecrawl client helpers now have comprehensive unit coverage, reducing the risk of regressions when the functions are modified.

Evidence

Reproducibility: not applicable. This PR adds direct coverage for existing helper behavior rather than reporting a user-visible runtime bug. Source inspection confirms the helper behavior the tests target.

Direct behavior probe:

$ node --import tsx -e "import('./extensions/firecrawl/src/firecrawl-client.js').then((m) => { const t = m.testing; const results = []; try { t.assertFirecrawlScrapeTargetAllowed('https://example.com'); results.push({desc:'valid HTTPS', pass: true}); } catch(e) { results.push({desc:'valid HTTPS', pass: false, err: e.message}); } try { t.assertFirecrawlScrapeTargetAllowed('ftp://bad.com'); results.push({desc:'blocked FTP', pass: false}); } catch(e) { results.push({desc:'blocked FTP', pass: true}); } try { t.assertFirecrawlScrapeTargetAllowed('http://127.0.0.1'); results.push({desc:'blocked localhost', pass: false}); } catch(e) { results.push({desc:'blocked localhost', pass: true}); } const items = t.resolveSearchItems({ data: [{ url:'https://a.com', title:'A' }, { url:'https://b.com', title:'B' }] }); results.push({desc:'resolveSearchItems count', pass: items.length === 2}); const parsed = t.parseFirecrawlScrapePayload({ url: 'https://example.com/page', extractMode: 'markdown', maxChars: 50000, payload: { data: { markdown: '# Hello' } } }); results.push({desc:'parseFirecrawlScrapePayload extractor', pass: parsed.extractor === 'firecrawl'}); results.push({desc:'parseFirecrawlScrapePayload has text', pass: typeof parsed.text === 'string' && parsed.text.length > 0}); console.log(JSON.stringify(results, null, 2)); });
[
  {
    "desc": "valid HTTPS",
    "pass": true
  },
  {
    "desc": "blocked FTP",
    "pass": true
  },
  {
    "desc": "blocked localhost",
    "pass": true
  },
  {
    "desc": "resolveSearchItems count",
    "pass": true
  },
  {
    "desc": "parseFirecrawlScrapePayload extractor",
    "pass": true
  },
  {
    "desc": "parseFirecrawlScrapePayload has text",
    "pass": true
  }
]

Unit test run:

$ pnpm test extensions/firecrawl/src/firecrawl-client.test.ts

 RUN  v4.1.8

 Test Files  1 passed (1)
      Tests  52 passed (52)

clawsweeper · 2026-06-29T07:54:25Z

Codex review: needs maintainer review before merge. Reviewed June 29, 2026, 4:59 AM ET / 08:59 UTC.

Summary
The branch adds a Firecrawl client unit-test file for URL safety, search-item normalization, and scrape payload parsing, and updates extension test planner expectations for Firecrawl's second test file.

PR surface: Tests +735. Total +735 across 2 files.

Reproducibility: not applicable. This PR adds regression coverage rather than reporting a runtime bug. The reviewed path is source-verifiable through the existing Firecrawl helper exports and adjacent tool tests.

Review metrics: none identified.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

none.

Next step before merge

[P2] No repair lane is needed; the remaining action is ordinary maintainer review and final PR checks for a clean test-only change.

Security
Cleared: The diff is test-only plus test-runner expectation updates, with no dependency, workflow, secret, runtime, or supply-chain surface changed.

Review details

Best possible solution:

Land or lightly refine the dedicated client tests while keeping the Firecrawl runtime behavior unchanged.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR adds regression coverage rather than reporting a runtime bug. The reviewed path is source-verifiable through the existing Firecrawl helper exports and adjacent tool tests.

Is this the best way to solve the issue?

Yes; a colocated unit-test file for the existing testing helper exports is an appropriate low-risk way to protect Firecrawl client behavior. I did not find a narrower runtime or API change that should replace this test-only approach.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ff1e7e1305cc.

Label changes

Label justifications:

P3: This is low-risk test coverage for existing Firecrawl helper behavior with no runtime, config, API, migration, or user-visible behavior change.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal evidence from a direct Node behavior probe and a focused Firecrawl unit-test run showing the added helper coverage passing.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal evidence from a direct Node behavior probe and a focused Firecrawl unit-test run showing the added helper coverage passing.

Evidence reviewed

PR surface:

Tests +735. Total +735 across 2 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	2	739	4	+735
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	2	739	4	+735

What I checked:

Changed surface: The PR adds extensions/firecrawl/src/firecrawl-client.test.ts covering assertFirecrawlScrapeTargetAllowed, resolveSearchItems, and parseFirecrawlScrapePayload, plus updates Firecrawl exact-exclude expectations in test/scripts/test-extension.test.ts. (extensions/firecrawl/src/firecrawl-client.test.ts:20, 0f3bdb731d51)
Current helper behavior: Current main exports the targeted helper functions through testing, and the runtime callers use them from search/scrape flows, so direct unit coverage is aimed at an existing internal test seam. (extensions/firecrawl/src/firecrawl-client.ts:612, ff1e7e1305cc)
Adjacent coverage read: Current main already has broader Firecrawl tool tests that exercise scrape parsing, search item normalization, SSRF blocking, endpoint validation, and runtime request paths; the PR adds more granular helper coverage rather than replacing runtime coverage. (extensions/firecrawl/src/firecrawl-tools.test.ts:128, ff1e7e1305cc)
Test planner contract: The extension test planner counts tracked *.test.ts files with git ls-files, so adding a tracked Firecrawl test file makes the updated testFileCount and exact-exclude expectations coherent on the PR branch. (scripts/lib/extension-test-plan.mjs:83, ff1e7e1305cc)
Live PR state and proof: GitHub reports the PR as mergeable and clean at head 0f3bdb731d51e51bfe13a969c0560a81292f2062; the PR body includes a direct Node behavior probe and a focused Firecrawl test run with 52 passing tests, and current CI checks are green for the relevant lanes. (0f3bdb731d51)

Likely related people:

xydigit-sj: git blame and git log --follow show the current Firecrawl client and adjacent tool tests in current main coming from commit 00c9ac55d664a4bf4cfa867e2063fcedeedb6cc6, merged via fix(secrets): skip PLAINTEXT_FOUND for known non-secret apiKey markers #97622. (role: introduced current Firecrawl client/test surface; confidence: high; commits: 00c9ac55d664; files: extensions/firecrawl/src/firecrawl-client.ts, extensions/firecrawl/src/firecrawl-tools.test.ts, test/scripts/test-extension.test.ts)
vincentkoc: Live PR metadata shows vincentkoc merged the current-main Firecrawl client/test commit, and feat(firecrawl): add keyless scrape support #94551 recently changed the same Firecrawl client and test files for keyless scrape support. (role: recent Firecrawl area contributor and merger; confidence: medium; commits: 00c9ac55d664, beea31a6b5da; files: extensions/firecrawl/src/firecrawl-client.ts, extensions/firecrawl/src/firecrawl-tools.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

solodmd · 2026-06-29T08:13:20Z

Fixed the TS2345 type error on rawLength — cast to as number since parseFirecrawlScrapePayload returns Record<string, unknown>.

Type check: pnpm tsgo:extensions:test ✅
Tests: 52/52 passed ✅

@clawsweeper re-review

clawsweeper · 2026-06-29T08:13:24Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

solodmd · 2026-06-29T08:42:24Z

Fixed the checks-node-compact-small-whole-2 failure — the test-extension.test.ts tests track testFileCount per extension and --exclude coverage for each extension's test files. Since firecrawl now has 2 test files (firecrawl-tools.test.ts + firecrawl-client.test.ts), updated the batching expectations:

testFileCount: 1 → 2
exclude-both tests: exclude both files instead of just firecrawl-tools.test.ts

All 44 tooling tests + 52 firecrawl tests pass locally. ✅

@clawsweeper re-review

clawsweeper · 2026-06-29T08:42:27Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

solodmd · 2026-06-29T08:45:39Z

Updated PR body with Direct behavior probe matching the pattern from recently merged test-only PRs (e.g. #96736, #96448).

@clawsweeper re-review

…law#97714)

openclaw-barnacle Bot added extensions: firecrawl size: L labels Jun 29, 2026

solodmd force-pushed the test/firecrawl-client-unit-tests branch from 3e44220 to f4af21b Compare June 29, 2026 08:13

test(firecrawl): add unit tests for firecrawl client functions

0f3bdb7

solodmd force-pushed the test/firecrawl-client-unit-tests branch from f4af21b to 0f3bdb7 Compare June 29, 2026 08:42

vincentkoc merged commit 86b9b88 into openclaw:main Jun 29, 2026
119 of 126 checks passed

github-actions Bot mentioned this pull request Jun 29, 2026

📡 Upstream Digest — 2026-06-29 16:52 UTC curtismercier/openclaw-mods#1174

Open

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jun 30, 2026

test(firecrawl): add unit tests for firecrawl client functions (openc…

d54667e

…law#97714)

QiuYuang pushed a commit to QiuYuang/openclaw that referenced this pull request Jul 1, 2026

test(firecrawl): add unit tests for firecrawl client functions (openc…

7298ade

…law#97714)

chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 1, 2026

test(firecrawl): add unit tests for firecrawl client functions (openc…

26f0a89

…law#97714)

chenyangjun-xy pushed a commit to chenyangjun-xy/openclaw that referenced this pull request Jul 3, 2026

test(firecrawl): add unit tests for firecrawl client functions (openc…

30ed8fb

…law#97714)

vincentkoc mentioned this pull request Jul 6, 2026

chore(jobs): prune resolved OpenClaw inbox jobs openclaw/clownfish#221

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

test(firecrawl): add unit tests for firecrawl client functions#97714

test(firecrawl): add unit tests for firecrawl client functions#97714
vincentkoc merged 1 commit into
openclaw:mainfrom
solodmd:test/firecrawl-client-unit-tests

solodmd commented Jun 29, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

solodmd commented Jun 29, 2026

Uh oh!

clawsweeper Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

solodmd commented Jun 29, 2026

Uh oh!

clawsweeper Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

solodmd commented Jun 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

solodmd commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

solodmd commented Jun 29, 2026

Uh oh!

clawsweeper Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

solodmd commented Jun 29, 2026

Uh oh!

clawsweeper Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

solodmd commented Jun 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

solodmd commented Jun 29, 2026 •

edited

Loading

clawsweeper Bot commented Jun 29, 2026 •

edited

Loading

clawsweeper Bot commented Jun 29, 2026 •

edited

Loading

clawsweeper Bot commented Jun 29, 2026 •

edited

Loading