Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { beforeEach, describe, expect, it, vi } from "vitest";
import { RankTrackingService } from "./RankTrackingService";
const mocks = vi.hoisted(() => ({
getConfigById: vi.fn(),
getKeywordsForConfig: vi.fn(),
addKeywordsToConfig: vi.fn(),
removeKeywordsFromConfig: vi.fn(),
updateKeywordMetrics: vi.fn(),
isHostedServerAuthMode: vi.fn(),
customerHasPaidPlan: vi.fn(),
beginRankCheckRun: vi.fn(),
createDataforseoClient: vi.fn(),
fetchKeywordMetricsForList: vi.fn(),
}));
vi.mock("cloudflare:workers", () => ({ env: { RANK_CHECK_WORKFLOW: {} } }));
vi.mock(
"@/server/features/rank-tracking/repositories/RankTrackingRepository",
() => ({ RankTrackingRepository: mocks }),
);
vi.mock("@/server/lib/runtime-env", () => ({
isHostedServerAuthMode: mocks.isHostedServerAuthMode,
}));
vi.mock("@/server/billing/subscription", () => ({
customerHasPaidPlan: mocks.customerHasPaidPlan,
}));
vi.mock("@/server/features/rank-tracking/services/rankCheckRunGuards", () => ({
beginRankCheckRun: mocks.beginRankCheckRun,
reconcileActiveRankCheckRun: vi.fn(),
}));
vi.mock("@/server/lib/dataforseo", () => ({
createDataforseoClient: mocks.createDataforseoClient,
fetchKeywordMetricsForList: mocks.fetchKeywordMetricsForList,
}));
const config = {
id: "config_1",
projectId: "project_1",
domain: "example.com",
locationCode: 2840,
languageCode: "en",
locationName: null,
devices: "both" as const,
serpDepth: 10,
scheduleInterval: "weekly" as const,
};
const billingCustomer = {
userId: "user_1",
userEmail: "[email protected]",
organizationId: "org_1",
projectId: "project_1",
};
describe("RankTrackingService management invariants", () => {
beforeEach(() => {
mocks.getConfigById.mockResolvedValue(config);
mocks.getKeywordsForConfig.mockResolvedValue([
{ id: "kw_1", keyword: "seo" },
{ id: "kw_2", keyword: "audit" },
]);
// Persistent implementations survive clearMocks, so the billing gates get
// explicit defaults; the plan tests override them per case.
mocks.isHostedServerAuthMode.mockResolvedValue(true);
mocks.customerHasPaidPlan.mockResolvedValue(true);
});
it("reports only keyword rows actually inserted", async () => {
mocks.getKeywordsForConfig.mockResolvedValue([]);
mocks.addKeywordsToConfig.mockImplementation(
async (rows: Array<{ id: string }>) => [rows[0]?.id],
);
const result = await RankTrackingService.addKeywords(
"config_1",
"project_1",
["SEO", "seo", "technical seo"],
{ kind: "direct_user_action" },
);
expect(result).toMatchObject({ added: 1 });
expect(result.addedIds).toHaveLength(1);
expect(mocks.addKeywordsToConfig).toHaveBeenCalledWith([
expect.objectContaining({ keyword: "seo" }),
expect.objectContaining({ keyword: "technical seo" }),
]);
});
it("keeps case as typed when matchCase is set, alongside the lowercase keyword", async () => {
mocks.getKeywordsForConfig.mockResolvedValue([
{ id: "kw_1", keyword: "nodex" },
]);
mocks.addKeywordsToConfig.mockImplementation(
async (rows: Array<{ id: string }>) => rows.map((row) => row.id),
);
await RankTrackingService.addKeywords(
"config_1",
"project_1",
["Nodex"],
{ kind: "direct_user_action" },
true,
);
expect(mocks.addKeywordsToConfig).toHaveBeenCalledWith([
expect.objectContaining({ keyword: "Nodex", matchCase: true }),
]);
});
it("requires an approved estimate before increasing scheduled spend", async () => {
mocks.getKeywordsForConfig.mockResolvedValue([]);
const error: unknown = await RankTrackingService.addKeywords(
"config_1",
"project_1",
["seo", "technical seo"],
{ kind: "credit_ceiling" },
).catch((cause: unknown) => cause);
expect(error).toBeInstanceOf(Error);
if (!(error instanceof Error) || !("code" in error)) throw error;
expect(error.code).toBe("VALIDATION_ERROR");
expect(error.message).toContain("including retries");
expect(mocks.addKeywordsToConfig).not.toHaveBeenCalled();
});
it("adds scheduled keywords at the approved estimate", async () => {
mocks.getKeywordsForConfig
.mockResolvedValueOnce([])
.mockResolvedValueOnce([
{ keyword: "seo" },
{ keyword: "technical seo" },
]);
mocks.addKeywordsToConfig.mockImplementation(
async (rows: Array<{ id: string }>) => rows.map((row) => row.id),
);
await expect(
RankTrackingService.addKeywords(
"config_1",
"project_1",
["seo", "technical seo"],
{
kind: "credit_ceiling",
maxEstimatedScheduledCheckCredits: 12,
},
),
).resolves.toMatchObject({
added: 2,
scheduledEstimate: {
scheduleInterval: "weekly",
costCredits: 12,
checksPerMonth: 4,
},
});
expect(mocks.addKeywordsToConfig).toHaveBeenCalledTimes(1);
});
it("rolls back its inserts when a concurrent add exceeds the estimate", async () => {
mocks.getKeywordsForConfig
.mockResolvedValueOnce([])
.mockResolvedValueOnce([
{ keyword: "seo" },
{ keyword: "technical seo" },
{ keyword: "concurrent add" },
]);
mocks.addKeywordsToConfig.mockImplementation(
async (rows: Array<{ id: string }>) => rows.map((row) => row.id),
);
mocks.removeKeywordsFromConfig.mockImplementation(
async (ids: string[]) => ids,
);
const error: unknown = await RankTrackingService.addKeywords(
"config_1",
"project_1",
["seo", "technical seo"],
{
kind: "credit_ceiling",
maxEstimatedScheduledCheckCredits: 12,
},
).catch((cause: unknown) => cause);
expect(error).toBeInstanceOf(Error);
if (!(error instanceof Error) || !("code" in error)) throw error;
expect(error.code).toBe("VALIDATION_ERROR");
expect(mocks.removeKeywordsFromConfig).toHaveBeenCalledWith(
expect.arrayContaining([expect.any(String), expect.any(String)]),
"config_1",
);
});
it("does not require MCP approval for a manual tracker", async () => {
mocks.getConfigById.mockResolvedValue({
...config,
scheduleInterval: "manual",
});
mocks.getKeywordsForConfig.mockResolvedValue([]);
mocks.addKeywordsToConfig.mockImplementation(
async (rows: Array<{ id: string }>) => rows.map((row) => row.id),
);
await expect(
RankTrackingService.addKeywords("config_1", "project_1", ["seo"], {
kind: "credit_ceiling",
}),
).resolves.toMatchObject({ added: 1, scheduledEstimate: undefined });
expect(mocks.getKeywordsForConfig).toHaveBeenCalledTimes(1);
});
it("rejects a hosted unpaid run before keyword or workflow work", async () => {
mocks.isHostedServerAuthMode.mockResolvedValue(true);
mocks.customerHasPaidPlan.mockResolvedValue(false);
await expect(
RankTrackingService.triggerCheck({
configId: "config_1",
projectId: "project_1",
billingCustomer,
}),
).rejects.toMatchObject({ code: "PAYMENT_REQUIRED" });
expect(mocks.getKeywordsForConfig).not.toHaveBeenCalled();
expect(mocks.beginRankCheckRun).not.toHaveBeenCalled();
});
it("allows paid hosted and self-hosted runs", async () => {
mocks.beginRankCheckRun.mockResolvedValue({
ok: true,
runId: "run_1",
});
mocks.isHostedServerAuthMode.mockResolvedValue(true);
mocks.customerHasPaidPlan.mockResolvedValue(true);
await expect(
RankTrackingService.triggerCheck({
configId: "config_1",
projectId: "project_1",
billingCustomer,
}),
).resolves.toEqual({ ok: true, runId: "run_1" });
mocks.isHostedServerAuthMode.mockResolvedValue(false);
// Isolate the second half of this test so it proves self-hosted mode skips
// the hosted billing lookup.
mocks.customerHasPaidPlan.mockClear();
await expect(
RankTrackingService.triggerCheck({
configId: "config_1",
projectId: "project_1",
billingCustomer,
}),
).resolves.toEqual({ ok: true, runId: "run_1" });
expect(mocks.customerHasPaidPlan).not.toHaveBeenCalled();
});
it("starts a run only at or below its approved credit ceiling", async () => {
mocks.beginRankCheckRun.mockResolvedValue({ ok: true, runId: "run_1" });
const run = {
configId: "config_1",
projectId: "project_1",
billingCustomer,
};
const error: unknown = await RankTrackingService.triggerCheck({
...run,
maxCostCredits: 19,
}).catch((cause: unknown) => cause);
expect(error).toBeInstanceOf(Error);
if (!(error instanceof Error) || !("code" in error)) throw error;
expect(error.code).toBe("VALIDATION_ERROR");
expect(error.message).toContain("costs 20 credits");
expect(mocks.beginRankCheckRun).not.toHaveBeenCalled();
await expect(
RankTrackingService.triggerCheck({ ...run, maxCostCredits: 20 }),
).resolves.toEqual({ ok: true, runId: "run_1" });
expect(mocks.beginRankCheckRun).toHaveBeenCalledWith(
expect.objectContaining({ maxCostCredits: 20 }),
);
});
it("rejects hosted unpaid metrics refresh before provider work", async () => {
mocks.isHostedServerAuthMode.mockResolvedValue(true);
mocks.customerHasPaidPlan.mockResolvedValue(false);
await expect(
RankTrackingService.refreshKeywordMetrics(
"config_1",
"project_1",
billingCustomer,
),
).rejects.toMatchObject({ code: "PAYMENT_REQUIRED" });
expect(mocks.createDataforseoClient).not.toHaveBeenCalled();
expect(mocks.fetchKeywordMetricsForList).not.toHaveBeenCalled();
});
it("matches metrics back to a cased keyword and its lowercase twin", async () => {
mocks.isHostedServerAuthMode.mockResolvedValue(false);
mocks.createDataforseoClient.mockReturnValue({});
mocks.getKeywordsForConfig.mockResolvedValue([
{ id: "kw_1", keyword: "Nodex" },
{ id: "kw_2", keyword: "nodex" },
]);
// DataForSEO echoes keywords back lowercased.
mocks.fetchKeywordMetricsForList.mockResolvedValue([
{ keyword: "nodex", searchVolume: 90, keywordDifficulty: 12, cpc: 0.5 },
]);
await expect(
RankTrackingService.refreshKeywordMetrics(
"config_1",
"project_1",
billingCustomer,
),
).resolves.toEqual({ updated: 2 });
expect(mocks.fetchKeywordMetricsForList).toHaveBeenCalledWith(
{},
expect.objectContaining({ keywords: ["nodex"] }),
);
expect(mocks.updateKeywordMetrics).toHaveBeenCalledWith([
expect.objectContaining({ id: "kw_1", searchVolume: 90 }),
expect.objectContaining({ id: "kw_2", searchVolume: 90 }),
]);
});
it("rejects missing or foreign trackers with NOT_FOUND before mutation", async () => {
mocks.getConfigById.mockResolvedValue(null);
await expect(
RankTrackingService.removeKeywords("foreign", "project_1", ["kw_1"]),
).rejects.toMatchObject({ code: "NOT_FOUND" });
expect(mocks.removeKeywordsFromConfig).not.toHaveBeenCalled();
});
});