Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

ci: add docs test suite (static + integration)

Sushmithamallesh93020e1c6e0c
diff --git a/.github/workflows/docs-tests.yml b/.github/workflows/docs-tests.yml
new file mode 100644
index 000000000..bfa00cb4e
--- /dev/null
+++ b/.github/workflows/docs-tests.yml
@@ -0,0 +1,56 @@
+name: Docs - Tests
+
+on:
+ pull_request:
+ paths:
+ - 'docs/**'
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: ./docs
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v6
+
+ - name: Setup Bun
+ uses: oven-sh/setup-bun@v2
+ with:
+ bun-version-file: '.bun-version'
+
+ - name: Install dependencies
+ run: bun install
+
+ - name: Run static tests
+ run: bun run test
+
+ - name: Build
+ run: bun run build
+
+ - name: Start server and run integration tests
+ run: |
+ bun run start &
+ SERVER_PID=$!
+
+ echo "Waiting for server to start..."
+ for i in $(seq 1 30); do
+ if curl -s http://localhost:3000 > /dev/null 2>&1; then
+ echo "Server is ready!"
+ break
+ fi
+ if [ $i -eq 30 ]; then
+ echo "Server failed to start within 30 seconds"
+ kill $SERVER_PID 2>/dev/null || true
+ exit 1
+ fi
+ sleep 1
+ done
+
+ bun run test:integration
+ TEST_EXIT=$?
+
+ kill $SERVER_PID 2>/dev/null || true
+ exit $TEST_EXIT
diff --git a/docs/package.json b/docs/package.json
index 9178920a7..4e7e99256 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -11,7 +11,9 @@
"lint": "eslint",
"lint:links": "bun scripts/validate-links.ts",
"generate:toolkits": "bun scripts/generate-toolkits.ts",
- "generate:api-index": "bun scripts/generate-api-index.ts"
+ "generate:api-index": "bun scripts/generate-api-index.ts",
+ "test": "bun test tests/static/",
+ "test:integration": "bun test tests/integration/ --timeout 30000"
},
"dependencies": {
"@radix-ui/react-tabs": "^1.1.13",
diff --git a/docs/tests/integration/helpers.ts b/docs/tests/integration/helpers.ts
new file mode 100644
index 000000000..185de4469
--- /dev/null
+++ b/docs/tests/integration/helpers.ts
@@ -0,0 +1,43 @@
+/** Shared helpers for integration tests that hit the running dev/prod server. */
+
+export const BASE_URL = process.env.TEST_BASE_URL || "http://localhost:3000";
+
+/** Fetch a URL from the docs server with a timeout */
+export async function fetchPage(
+ path: string,
+ options?: RequestInit & { timeout?: number }
+): Promise<Response> {
+ const { timeout = 10_000, ...fetchOpts } = options || {};
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), timeout);
+
+ try {
+ return await fetch(`${BASE_URL}${path}`, {
+ ...fetchOpts,
+ signal: controller.signal,
+ redirect: "follow",
+ });
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+/** Fetch without following redirects to inspect redirect behavior */
+export async function fetchNoRedirect(
+ path: string,
+ options?: RequestInit & { timeout?: number }
+): Promise<Response> {
+ const { timeout = 10_000, ...fetchOpts } = options || {};
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), timeout);
+
+ try {
+ return await fetch(`${BASE_URL}${path}`, {
+ ...fetchOpts,
+ signal: controller.signal,
+ redirect: "manual",
+ });
+ } finally {
+ clearTimeout(timer);
+ }
+}
diff --git a/docs/tests/integration/llm-endpoints.test.ts b/docs/tests/integration/llm-endpoints.test.ts
new file mode 100644
index 000000000..1c0cf7632
--- /dev/null
+++ b/docs/tests/integration/llm-endpoints.test.ts
@@ -0,0 +1,79 @@
+/**
+ * LLM endpoint integration tests.
+ *
+ * Validates that .md endpoints return well-formed markdown with proper
+ * content-type headers and guardrails.
+ */
+import { describe, test, expect } from "bun:test";
+import { fetchPage } from "./helpers";
+
+describe("LLM endpoints - llms.txt", () => {
+ test("/llms.txt returns 200 with text content", async () => {
+ const res = await fetchPage("/llms.txt");
+ expect(res.status).toBe(200);
+
+ const text = await res.text();
+ expect(text.length).toBeGreaterThan(100);
+ // Should contain page links
+ expect(text).toContain("composio");
+ });
+});
+
+describe("LLM endpoints - .md pages", () => {
+ const MD_PAGES = [
+ { path: "/docs/quickstart.md", name: "Quickstart" },
+ { path: "/docs/authentication.md", name: "Authentication" },
+ { path: "/docs/tools-and-toolkits.md", name: "Tools & Toolkits" },
+ ];
+
+ for (const { path, name } of MD_PAGES) {
+ test(`${name} (${path}) returns markdown`, async () => {
+ const res = await fetchPage(path);
+ expect(res.status).toBe(200);
+
+ const contentType = res.headers.get("content-type") || "";
+ expect(contentType).toContain("text/markdown");
+ });
+
+ test(`${name} (${path}) has a title heading`, async () => {
+ const res = await fetchPage(path);
+ const text = await res.text();
+ // Should start with a markdown heading
+ expect(text).toMatch(/^#\s+.+/);
+ });
+
+ test(`${name} (${path}) has meaningful content (> 200 chars)`, async () => {
+ const res = await fetchPage(path);
+ const text = await res.text();
+ expect(text.length).toBeGreaterThan(200);
+ });
+ }
+});
+
+describe("LLM endpoints - guardrails", () => {
+ test("quickstart.md includes guardrail content", async () => {
+ const res = await fetchPage("/docs/quickstart.md");
+ const text = await res.text();
+ // Default guardrails should be appended (session-based pattern)
+ // The exact content varies but should include the footer
+ expect(text).toContain("More documentation");
+ });
+});
+
+describe("LLM endpoints - toolkit markdown", () => {
+ test("/toolkits.md returns toolkit index", async () => {
+ const res = await fetchPage("/toolkits.md");
+ expect(res.status).toBe(200);
+
+ const text = await res.text();
+ expect(text).toContain("Toolkits");
+ expect(text.toLowerCase()).toContain("github");
+ });
+});
+
+describe("LLM endpoints - error handling", () => {
+ test("non-existent .md page returns 404", async () => {
+ const res = await fetchPage("/docs/nonexistent-page-xyz.md");
+ expect(res.status).toBe(404);
+ });
+});
diff --git a/docs/tests/integration/redirects.test.ts b/docs/tests/integration/redirects.test.ts
new file mode 100644
index 000000000..f5498dda4
--- /dev/null
+++ b/docs/tests/integration/redirects.test.ts
@@ -0,0 +1,59 @@
+/**
+ * Redirect integration tests.
+ *
+ * Validates that key redirect patterns work correctly — old URLs redirect
+ * to valid destinations that return 200.
+ */
+import { describe, test, expect } from "bun:test";
+import { fetchPage, fetchNoRedirect, BASE_URL } from "./helpers";
+
+/** Sample of important redirects to test (from next.config.mjs) */
+const REDIRECTS = [
+ { from: "/", to: "/docs" },
+ { from: "/examples", to: "/cookbooks" },
+ { from: "/api-reference", to: "/reference" },
+ { from: "/providers/openai", to: "/docs/providers/openai" },
+ { from: "/providers/anthropic", to: "/docs/providers/anthropic" },
+ { from: "/tools", to: "/toolkits" },
+ { from: "/docs/fetching-tools", to: "/docs/tools-direct/fetching-tools" },
+ { from: "/docs/custom-tools", to: "/docs/tools-direct/custom-tools" },
+ { from: "/docs/how-tools-work", to: "/docs/tools-and-toolkits" },
+ { from: "/authentication", to: "/docs/authentication" },
+ { from: "/changelog", to: "/docs/changelog" },
+ { from: "/docs/mcp-quickstart", to: "/docs/single-toolkit-mcp" },
+ { from: "/docs/welcome", to: "/docs" },
+ { from: "/docs/managed-authentication", to: "/docs/authentication" },
+];
+
+describe("Redirects - key patterns", () => {
+ for (const { from, to } of REDIRECTS) {
+ test(`${from} → ${to}`, async () => {
+ const res = await fetchNoRedirect(from);
+ // Should be a 301 or 308 redirect
+ expect([301, 302, 307, 308]).toContain(res.status);
+
+ const location = res.headers.get("location") || "";
+ // Location might be absolute or relative
+ const normalizedLocation = location
+ .replace(BASE_URL, "")
+ .split("?")[0]; // Strip query params
+ expect(normalizedLocation).toBe(to);
+ });
+ }
+});
+
+describe("Redirects - destinations are valid", () => {
+ test("all redirect destinations return 200", async () => {
+ const destinations = [...new Set(REDIRECTS.map((r) => r.to))];
+ const failures: string[] = [];
+
+ for (const dest of destinations) {
+ const res = await fetchPage(dest);
+ if (res.status !== 200) {
+ failures.push(`${dest} returned ${res.status}`);
+ }
+ }
+
+ expect(failures).toEqual([]);
+ });
+});
diff --git a/docs/tests/integration/rendering.test.ts b/docs/tests/integration/rendering.test.ts
new file mode 100644
index 000000000..4f8df444c
--- /dev/null
+++ b/docs/tests/integration/rendering.test.ts
@@ -0,0 +1,64 @@
+/**
+ * Page rendering integration tests.
+ *
+ * Validates that critical pages render successfully (200), return HTML,
+ * and contain expected content markers.
+ */
+import { describe, test, expect } from "bun:test";
+import { fetchPage } from "./helpers";
+
+/** Critical pages that must always render */
+const CRITICAL_PAGES = [
+ { path: "/docs", name: "Docs home" },
+ { path: "/docs/quickstart", name: "Quickstart" },
+ { path: "/docs/authentication", name: "Authentication" },
+ { path: "/docs/tools-and-toolkits", name: "Tools & Toolkits" },
+ { path: "/docs/users-and-sessions", name: "Users & Sessions" },
+ { path: "/cookbooks", name: "Cookbooks index" },
+ { path: "/toolkits", name: "Toolkits index" },
+ { path: "/reference", name: "Reference index" },
+];
+
+describe("Page rendering - critical pages", () => {
+ for (const { path, name } of CRITICAL_PAGES) {
+ test(`${name} (${path}) returns 200`, async () => {
+ const res = await fetchPage(path);
+ expect(res.status).toBe(200);
+ });
+
+ test(`${name} (${path}) returns HTML`, async () => {
+ const res = await fetchPage(path);
+ const contentType = res.headers.get("content-type") || "";
+ expect(contentType).toContain("text/html");
+ });
+ }
+});
+
+describe("Page rendering - content markers", () => {
+ test("docs home contains navigation elements", async () => {
+ const res = await fetchPage("/docs");
+ const html = await res.text();
+ // Should have some sidebar/nav content
+ expect(html).toContain("Quickstart");
+ });
+
+ test("quickstart page contains expected content", async () => {
+ const res = await fetchPage("/docs/quickstart");
+ const html = await res.text();
+ expect(html.toLowerCase()).toContain("composio");
+ });
+
+ test("toolkits page renders toolkit cards", async () => {
+ const res = await fetchPage("/toolkits");
+ const html = await res.text();
+ // Should contain at least one well-known toolkit
+ expect(html.toLowerCase()).toContain("github");
+ });
+});
+
+describe("Page rendering - error handling", () => {
+ test("non-existent page returns 404", async () => {
+ const res = await fetchPage("/docs/this-page-does-not-exist-ever");
+ expect(res.status).toBe(404);
+ });
+});
diff --git a/docs/tests/integration/search.test.ts b/docs/tests/integration/search.test.ts
new file mode 100644
index 000000000..e844e4bc1
--- /dev/null
+++ b/docs/tests/integration/search.test.ts
@@ -0,0 +1,55 @@
+/**
+ * Search API integration tests.
+ *
+ * Validates that the search endpoint returns relevant results for key terms.
+ */
+import { describe, test, expect } from "bun:test";
+import { fetchPage } from "./helpers";
+
+describe("Search API", () => {
+ test("returns results for 'authentication'", async () => {
+ const res = await fetchPage("/api/search?query=authentication");
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(Array.isArray(data)).toBe(true);
+ expect(data.length).toBeGreaterThan(0);
+
+ // At least one result should have a URL and title
+ const first = data[0];
+ expect(first).toHaveProperty("url");
+ expect(first).toHaveProperty("content");
+ });
+
+ test("returns results for 'quickstart'", async () => {
+ const res = await fetchPage("/api/search?query=quickstart");
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.length).toBeGreaterThan(0);
+ });
+
+ test("returns results for 'tools'", async () => {
+ const res = await fetchPage("/api/search?query=tools");
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.length).toBeGreaterThan(0);
+ });
+
+ test("returns empty array for nonsense query", async () => {
+ const res = await fetchPage("/api/search?query=xyzzy123nonexistent");
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(Array.isArray(data)).toBe(true);
+ // Should return no results (or very few) for gibberish
+ expect(data.length).toBeLessThan(3);
+ });
+
+ test("returns 400 or empty for missing query", async () => {
+ const res = await fetchPage("/api/search");
+ // Fumadocs returns 400 for missing query param
+ expect([200, 400]).toContain(res.status);
+ });
+});
diff --git a/docs/tests/static/content.test.ts b/docs/tests/static/content.test.ts
new file mode 100644
index 000000000..83d5583b7
--- /dev/null
+++ b/docs/tests/static/content.test.ts
@@ -0,0 +1,159 @@
+/**
+ * Content validation tests.
+ *
+ * Checks that all MDX pages have required frontmatter (title), are non-empty,
+ * and changelog entries use valid date formats.
+ */
+import { describe, test, expect } from "bun:test";
+import { readdir, readFile, stat } from "fs/promises";
+import { join, relative } from "path";
+
+const DOCS_DIR = join(import.meta.dir, "../../content/docs");
+const COOKBOOKS_DIR = join(import.meta.dir, "../../content/cookbooks");
+const CHANGELOG_DIR = join(import.meta.dir, "../../content/changelog");
+
+/** Recursively find all .mdx files */
+async function findMdxFiles(dir: string): Promise<string[]> {
+ const results: string[] = [];
+ let entries;
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return results;
+ }
+
+ for (const entry of entries) {
+ const fullPath = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ results.push(...(await findMdxFiles(fullPath)));
+ } else if (entry.name.endsWith(".mdx")) {
+ results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+/** Extract frontmatter from MDX content */
+function parseFrontmatter(content: string): Record<string, string> | null {
+ const match = content.match(/^---\n([\s\S]*?)\n---/);
+ if (!match) return null;
+
+ const fm: Record<string, string> = {};
+ for (const line of match[1].split("\n")) {
+ const colonIdx = line.indexOf(":");
+ if (colonIdx > 0) {
+ const key = line.slice(0, colonIdx).trim();
+ const value = line.slice(colonIdx + 1).trim();
+ fm[key] = value;
+ }
+ }
+ return fm;
+}
+
+describe("Content - frontmatter validation", () => {
+ test("all docs pages have a title", async () => {
+ const files = await findMdxFiles(DOCS_DIR);
+ const missingTitle: string[] = [];
+
+ for (const file of files) {
+ const content = await readFile(file, "utf-8");
+ const fm = parseFrontmatter(content);
+ if (!fm || !fm.title) {
+ missingTitle.push(relative(DOCS_DIR, file));
+ }
+ }
+
+ expect(missingTitle).toEqual([]);
+ });
+
+ test("all cookbooks pages have a title", async () => {
+ const files = await findMdxFiles(COOKBOOKS_DIR);
+ const missingTitle: string[] = [];
+
+ for (const file of files) {
+ const content = await readFile(file, "utf-8");
+ const fm = parseFrontmatter(content);
+ if (!fm || !fm.title) {
+ missingTitle.push(relative(COOKBOOKS_DIR, file));
+ }
+ }
+
+ expect(missingTitle).toEqual([]);
+ });
+});
+
+describe("Content - no empty pages", () => {
+ test("docs pages have meaningful content (> 50 chars after frontmatter)", async () => {
+ const files = await findMdxFiles(DOCS_DIR);
+ const empty: string[] = [];
+
+ for (const file of files) {
+ const content = await readFile(file, "utf-8");
+ // Strip frontmatter
+ const body = content.replace(/^---[\s\S]*?---\n*/, "").trim();
+ if (body.length < 50) {
+ empty.push(relative(DOCS_DIR, file));
+ }
+ }
+
+ expect(empty).toEqual([]);
+ });
+});
+
+describe("Content - changelog validation", () => {
+ test("changelog files use MM-DD-YY naming pattern", async () => {
+ let entries;
+ try {
+ entries = await readdir(CHANGELOG_DIR);
+ } catch {
+ return;
+ }
+
+ // Files are named MM-DD-YY.mdx or MM-DD-YY-description.mdx
+ const nameRegex = /^\d{2}-\d{2}-\d{2}(-[\w-]+)?\.mdx$/;
+ const invalid: string[] = [];
+
+ for (const entry of entries) {
+ if (entry === "meta.json" || entry === ".DS_Store") continue;
+ if (!nameRegex.test(entry)) {
+ invalid.push(entry);
+ }
+ }
+
+ expect(invalid).toEqual([]);
+ });
+
+ test("changelog entries have a title and valid YYYY-MM-DD date in frontmatter", async () => {
+ let entries;
+ try {
+ entries = await readdir(CHANGELOG_DIR);
+ } catch {
+ return;
+ }
+
+ const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+ const errors: string[] = [];
+
+ for (const entry of entries) {
+ if (!entry.endsWith(".mdx")) continue;
+ const content = await readFile(join(CHANGELOG_DIR, entry), "utf-8");
+ const fm = parseFrontmatter(content);
+
+ if (!fm || !fm.title) {
+ errors.push(`${entry}: missing title`);
+ }
+
+ const dateValue = fm?.date?.replace(/["']/g, "");
+ if (!dateValue || !dateRegex.test(dateValue)) {
+ errors.push(`${entry}: missing or invalid date (expected YYYY-MM-DD)`);
+ } else {
+ const parsed = new Date(`${dateValue}T12:00:00`);
+ if (isNaN(parsed.getTime())) {
+ errors.push(`${entry}: date "${dateValue}" is not a valid calendar date`);
+ }
+ }
+ }
+
+ expect(errors).toEqual([]);
+ });
+});
diff --git a/docs/tests/static/navigation.test.ts b/docs/tests/static/navigation.test.ts
new file mode 100644
index 000000000..ed93b7caf
--- /dev/null
+++ b/docs/tests/static/navigation.test.ts
@@ -0,0 +1,151 @@
+/**
+ * Navigation completeness tests.
+ *
+ * Validates that every entry in meta.json files maps to a real .mdx file or
+ * directory, and that every content file is referenced in its parent meta.json.
+ */
+import { describe, test, expect } from "bun:test";
+import { readdir, readFile, stat } from "fs/promises";
+import { join, basename, dirname, relative } from "path";
+
+const CONTENT_DIR = join(import.meta.dir, "../../content/docs");
+
+/** Separator entries in meta.json start with --- */
+function isSeparator(entry: string): boolean {
+ return entry.startsWith("---");
+}
+
+/** Recursively find all meta.json files under a directory */
+async function findMetaFiles(dir: string): Promise<string[]> {
+ const results: string[] = [];
+ const entries = await readdir(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ results.push(...(await findMetaFiles(fullPath)));
+ } else if (entry.name === "meta.json") {
+ results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+/** Check if a path exists as a file or directory */
+async function exists(path: string): Promise<boolean> {
+ try {
+ await stat(path);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+describe("Navigation - meta.json validity", () => {
+ test("root meta.json entries all resolve to files or directories", async () => {
+ const metaPath = join(CONTENT_DIR, "meta.json");
+ const meta = JSON.parse(await readFile(metaPath, "utf-8"));
+ const missing: string[] = [];
+
+ for (const entry of meta.pages as string[]) {
+ if (isSeparator(entry)) continue;
+
+ const asFile = join(CONTENT_DIR, `${entry}.mdx`);
+ const asDir = join(CONTENT_DIR, entry);
+
+ const fileExists = await exists(asFile);
+ const dirExists = await exists(asDir);
+
+ if (!fileExists && !dirExists) {
+ missing.push(entry);
+ }
+ }
+
+ expect(missing).toEqual([]);
+ });
+
+ test("all nested meta.json entries resolve to files or directories", async () => {
+ const metaFiles = await findMetaFiles(CONTENT_DIR);
+ const errors: string[] = [];
+
+ for (const metaPath of metaFiles) {
+ const dir = dirname(metaPath);
+ const meta = JSON.parse(await readFile(metaPath, "utf-8"));
+ const relDir = relative(CONTENT_DIR, dir);
+
+ for (const entry of (meta.pages || []) as string[]) {
+ if (isSeparator(entry)) continue;
+
+ // Handle "..." (rest) entries which are valid fumadocs syntax
+ if (entry === "...") continue;
+
+ const asFile = join(dir, `${entry}.mdx`);
+ const asDir = join(dir, entry);
+
+ const fileExists = await exists(asFile);
+ const dirExists = await exists(asDir);
+
+ if (!fileExists && !dirExists) {
+ errors.push(`${relDir}/meta.json → "${entry}" (no .mdx file or directory found)`);
+ }
+ }
+ }
+
+ expect(errors).toEqual([]);
+ });
+
+ test("no orphan .mdx files missing from meta.json", async () => {
+ const metaFiles = await findMetaFiles(CONTENT_DIR);
+ const orphans: string[] = [];
+
+ // Check root level
+ const rootMetaPath = join(CONTENT_DIR, "meta.json");
+ const rootMeta = JSON.parse(await readFile(rootMetaPath, "utf-8"));
+ const rootEntries = new Set(
+ (rootMeta.pages as string[]).filter((e: string) => !isSeparator(e))
+ );
+ const rootFiles = await readdir(CONTENT_DIR, { withFileTypes: true });
+
+ for (const file of rootFiles) {
+ if (file.name === "meta.json") continue;
+ const name = file.isFile() ? basename(file.name, ".mdx") : file.name;
+ if (file.isFile() && !file.name.endsWith(".mdx")) continue;
+ if (!rootEntries.has(name)) {
+ orphans.push(`docs/${file.name}`);
+ }
+ }
+
+ // Check each nested directory that has a meta.json
+ for (const metaPath of metaFiles) {
+ if (metaPath === rootMetaPath) continue;
+ const dir = dirname(metaPath);
+ const meta = JSON.parse(await readFile(metaPath, "utf-8"));
+ const entries = new Set(
+ ((meta.pages || []) as string[]).filter((e: string) => !isSeparator(e))
+ );
+ // "..." means "include everything else", so skip orphan check
+ if (entries.has("...")) continue;
+
+ const files = await readdir(dir, { withFileTypes: true });
+ const relDir = relative(CONTENT_DIR, dir);
+
+ for (const file of files) {
+ if (file.name === "meta.json") continue;
+ const name = file.isFile() ? basename(file.name, ".mdx") : file.name;
+ if (file.isFile() && !file.name.endsWith(".mdx")) continue;
+ if (!entries.has(name)) {
+ orphans.push(`${relDir}/${file.name}`);
+ }
+ }
+ }
+
+ if (orphans.length > 0) {
+ console.warn(
+ `Found ${orphans.length} orphan file(s) not in any meta.json:\n` +
+ orphans.map((o) => ` - ${o}`).join("\n")
+ );
+ }
+ // Warn but don't fail — orphans aren't necessarily bugs
+ expect(orphans.length).toBeLessThan(20);
+ });
+});
diff --git a/docs/tests/static/toolkit-data.test.ts b/docs/tests/static/toolkit-data.test.ts
new file mode 100644
index 000000000..4b7c2c938
--- /dev/null
+++ b/docs/tests/static/toolkit-data.test.ts
@@ -0,0 +1,104 @@
+/**
+ * Toolkit data integrity tests.
+ *
+ * Validates that toolkits.json and toolkits-list.json exist, are valid JSON,
+ * and contain the expected structure.
+ */
+import { describe, test, expect } from "bun:test";
+import { readFile } from "fs/promises";
+import { join } from "path";
+
+const DATA_DIR = join(import.meta.dir, "../../public/data");
+
+interface ToolkitListItem {
+ slug: string;
+ name: string;
+ logo: string;
+ category: string;
+ toolCount: number;
+ triggerCount: number;
+}
+
+interface ToolkitFull extends ToolkitListItem {
+ description: string;
+ authSchemes: string[];
+ tools: Array<{ slug: string; name: string; description: string }>;
+}
+
+describe("Toolkit data - toolkits.json", () => {
+ let data: ToolkitFull[];
+
+ test("file exists and is valid JSON", async () => {
+ const raw = await readFile(join(DATA_DIR, "toolkits.json"), "utf-8");
+ data = JSON.parse(raw);
+ expect(Array.isArray(data)).toBe(true);
+ });
+
+ test("has a reasonable number of toolkits (> 50)", () => {
+ expect(data.length).toBeGreaterThan(50);
+ });
+
+ test("each toolkit has required fields", () => {
+ const invalid: string[] = [];
+
+ for (const toolkit of data) {
+ if (!toolkit.slug || typeof toolkit.slug !== "string") {
+ invalid.push(`missing slug: ${JSON.stringify(toolkit).slice(0, 80)}`);
+ continue;
+ }
+ if (!toolkit.name || typeof toolkit.name !== "string") {
+ invalid.push(`${toolkit.slug}: missing name`);
+ }
+ if (typeof toolkit.toolCount !== "number") {
+ invalid.push(`${toolkit.slug}: missing toolCount`);
+ }
+ if (!Array.isArray(toolkit.authSchemes)) {
+ invalid.push(`${toolkit.slug}: missing authSchemes array`);
+ }
+ }
+
+ expect(invalid).toEqual([]);
+ });
+
+ test("no duplicate slugs", () => {
+ const slugs = data.map((t) => t.slug);
+ const duplicates = slugs.filter((s, i) => slugs.indexOf(s) !== i);
+ expect(duplicates).toEqual([]);
+ });
+
+ test("well-known toolkits exist", () => {
+ const slugs = new Set(data.map((t) => t.slug));
+ const expected = ["github", "gmail", "slack", "notion"];
+ const missing = expected.filter((s) => !slugs.has(s));
+ expect(missing).toEqual([]);
+ });
+});
+
+describe("Toolkit data - toolkits-list.json", () => {
+ let data: ToolkitListItem[];
+
+ test("file exists and is valid JSON", async () => {
+ const raw = await readFile(join(DATA_DIR, "toolkits-list.json"), "utf-8");
+ data = JSON.parse(raw);
+ expect(Array.isArray(data)).toBe(true);
+ });
+
+ test("list count matches full data count", async () => {
+ const fullRaw = await readFile(join(DATA_DIR, "toolkits.json"), "utf-8");
+ const full = JSON.parse(fullRaw);
+ expect(data.length).toBe(full.length);
+ });
+
+ test("each entry has required list fields", () => {
+ const invalid: string[] = [];
+
+ for (const item of data) {
+ if (!item.slug) invalid.push("missing slug");
+ if (!item.name) invalid.push(`${item.slug}: missing name`);
+ if (typeof item.toolCount !== "number")
+ invalid.push(`${item.slug}: missing toolCount`);
+ }
+
+ expect(invalid).toEqual([]);
+ });
+});