Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

test: harden agent hint coverage

Rakshith Ramprakashbe9b223f4905
diff --git a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts b/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
index ababf54b3..9f9a2acfa 100644
--- a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
+++ b/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
@@ -120,6 +120,7 @@ describe("checkCreditsMiddleware – Autumn overage handling", () => {
const { res } = await runMiddleware(req);
expect(res.status).not.toHaveBeenCalled();
+ expect(res.locals.agentCreditsRemaining).toBe(5);
expect(req.body.limit).toBe(5);
expect(checkCreditsMock).toHaveBeenLastCalledWith(
expect.objectContaining({
diff --git a/apps/api/src/__tests__/snips/v2/agent-hints.test.ts b/apps/api/src/__tests__/snips/v2/agent-hints.test.ts
index 061d0f68f..30765b8d6 100644
--- a/apps/api/src/__tests__/snips/v2/agent-hints.test.ts
+++ b/apps/api/src/__tests__/snips/v2/agent-hints.test.ts
@@ -11,6 +11,42 @@ beforeAll(async () => {
}, 20000);
describeIf(TEST_PRODUCTION)("Agent hints", () => {
+ const missingPage = `${TEST_SUITE_WEBSITE}/agent-hints-not-found`;
+
+ it(
+ "adds a scrape-to-search hint for a missing source page",
+ async () => {
+ const response = await request(TEST_API_URL)
+ .post("/v2/scrape")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .set("X-Firecrawl-Agent-Hints", "true")
+ .send({ url: missingPage, timeout: scrapeTimeout });
+ expect(response.statusCode).toBe(200);
+ expect(response.body.success).toBe(true);
+ expect(response.body.data.metadata.statusCode).toBe(404);
+ expect(response.body.agent_hints).toEqual([
+ expect.stringContaining("POST /v2/search"),
+ ]);
+ },
+ scrapeTimeout + 10000,
+ );
+
+ it(
+ "keeps hints off when the opt-in header is false despite a hint condition",
+ async () => {
+ const response = await request(TEST_API_URL)
+ .post("/v2/scrape")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .set("X-Firecrawl-Agent-Hints", "false")
+ .send({ url: missingPage, timeout: scrapeTimeout });
+ expect(response.statusCode).toBe(200);
+ expect(response.body.success).toBe(true);
+ expect(response.body.data.metadata.statusCode).toBe(404);
+ expect(response.body).not.toHaveProperty("agent_hints");
+ },
+ scrapeTimeout + 10000,
+ );
+
it(
"does not add static feedback guidance to a completed scrape",
async () => {
diff --git a/apps/api/src/lib/agent-hints.test.ts b/apps/api/src/lib/agent-hints.test.ts
index 3a4cbe396..f2b1a9837 100644
--- a/apps/api/src/lib/agent-hints.test.ts
+++ b/apps/api/src/lib/agent-hints.test.ts
@@ -33,11 +33,13 @@ describe("deterministic agent hints", () => {
});
it("uses explicit page status instead of API 404s such as cache misses", () => {
- const result = hints({
- endpoint: "scrape",
- response: { success: true, data: { metadata: { statusCode: 404 } } },
- });
- expect(result.join(" ")).toContain("POST /v2/search");
+ for (const code of [404, 410]) {
+ const result = hints({
+ endpoint: "scrape",
+ response: { success: true, data: { metadata: { statusCode: code } } },
+ });
+ expect(result.join(" ")).toContain("POST /v2/search");
+ }
for (const code of [403, 429, 500]) {
expect(
hints({
diff --git a/apps/api/src/middlewares/__tests__/agent-hints.test.ts b/apps/api/src/middlewares/__tests__/agent-hints.test.ts
index 89df3b968..be1a2f45c 100644
--- a/apps/api/src/middlewares/__tests__/agent-hints.test.ts
+++ b/apps/api/src/middlewares/__tests__/agent-hints.test.ts
@@ -37,24 +37,44 @@ describe("agent hint response middleware", () => {
};
const response = await request(appFor({ body }))
.post("/")
- .set("X-Firecrawl-Agent-Hints", " TRUE ")
+ .set("X-Firecrawl-Agent-Hints", "TRUE")
.send({});
expect(response.statusCode).toBe(200);
expect(response.body).toMatchObject(body);
expect(response.body.agent_hints).toHaveLength(1);
});
- it("values other than true preserve the original envelope", async () => {
- const body = {
- success: true,
- data: { web: [{ url: "https://example.com" }] },
- };
- const response = await request(appFor({ body, remainingCredits: 0 }))
- .post("/")
- .set("X-Firecrawl-Agent-Hints", "false")
- .send({});
- expect(response.body).toEqual(body);
- });
+ it.each(["false", "1", "yes"])(
+ "header value %s preserves the original envelope",
+ async value => {
+ const body = {
+ success: true,
+ data: { web: [{ url: "https://example.com" }] },
+ };
+ const response = await request(appFor({ body, remainingCredits: 0 }))
+ .post("/")
+ .set("X-Firecrawl-Agent-Hints", value)
+ .send({});
+ expect(response.body).toEqual(body);
+ },
+ );
+
+ it.each([404, 410])(
+ "adds the scrape-to-search hint for page status %i",
+ async statusCode => {
+ const body = {
+ success: true,
+ data: { metadata: { statusCode } },
+ };
+ const response = await request(appFor({ endpoint: "scrape", body }))
+ .post("/")
+ .set("X-Firecrawl-Agent-Hints", "true")
+ .send({});
+ expect(response.body.agent_hints).toHaveLength(1);
+ expect(response.body.agent_hints[0]).toContain("POST /v2/search");
+ expect(response.body.agent_hints[0]).not.toContain("POST /v2/scrape");
+ },
+ );
it("does not add static feedback guidance to an otherwise hint-free result", async () => {
const response = await request(appFor())
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-hints.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-hints.test.ts
index 21e92c08b..066c15d64 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-hints.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/agent-hints.test.ts
@@ -22,12 +22,14 @@ function httpFor(body: object) {
}
describe("agent hints survive SDK response unwrapping", () => {
- it("preserves hints for empty searches without adding them to records", async () => {
+ it("preserves search hints without adding them to records", async () => {
+ const web = [{ url: "https://example.com" }];
const result = await search(
- httpFor({ success: true, data: { web: [] }, agent_hints: hints }),
+ httpFor({ success: true, data: { web }, agent_hints: hints }),
{ query: "test" },
);
- expect(result.web).toEqual([]);
+ expect(result.web).toEqual(web);
+ expect(result.web[0]).not.toHaveProperty("agent_hints");
expect(result.agent_hints).toEqual(hints);
expect(JSON.parse(JSON.stringify(result)).agent_hints).toEqual(hints);
});