@devries-cameron20 / composio-1 / commits / 93020e1c6
Fork 0

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)

Static tests (no server): navigation completeness, content/frontmatter validation, changelog format, toolkit data integrity. Integration tests (needs server): search API, page rendering, LLM markdown endpoints, redirect validation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 19, 2026 at 11:04 UTC 93020e1c6e0cf5f3db2500ee39fe4ce86eea7e55
10 files changed +773 -1
.github/workflows/docs-tests.yml new
+56
@@ -0,0 +1,56 @@
1 +name: Docs - Tests
2 +
3 +on:
4 + pull_request:
5 + paths:
6 + - 'docs/**'
7 +
8 +jobs:
9 + test:
10 + runs-on: ubuntu-latest
11 + defaults:
12 + run:
13 + working-directory: ./docs
14 +
15 + steps:
16 + - name: Checkout repository
17 + uses: actions/checkout@v6
18 +
19 + - name: Setup Bun
20 + uses: oven-sh/setup-bun@v2
21 + with:
22 + bun-version-file: '.bun-version'
23 +
24 + - name: Install dependencies
25 + run: bun install
26 +
27 + - name: Run static tests
28 + run: bun run test
29 +
30 + - name: Build
31 + run: bun run build
32 +
33 + - name: Start server and run integration tests
34 + run: |
35 + bun run start &
36 + SERVER_PID=$!
37 +
38 + echo "Waiting for server to start..."
39 + for i in $(seq 1 30); do
40 + if curl -s http://localhost:3000 > /dev/null 2>&1; then
41 + echo "Server is ready!"
42 + break
43 + fi
44 + if [ $i -eq 30 ]; then
45 + echo "Server failed to start within 30 seconds"
46 + kill $SERVER_PID 2>/dev/null || true
47 + exit 1
48 + fi
49 + sleep 1
50 + done
51 +
52 + bun run test:integration
53 + TEST_EXIT=$?
54 +
55 + kill $SERVER_PID 2>/dev/null || true
56 + exit $TEST_EXIT
docs/package.json
+3 -1
@@ -11,7 +11,9 @@
11 "lint": "eslint",
12 "lint:links": "bun scripts/validate-links.ts",
13 "generate:toolkits": "bun scripts/generate-toolkits.ts",
14 - "generate:api-index": "bun scripts/generate-api-index.ts"
14 + "generate:api-index": "bun scripts/generate-api-index.ts",
15 + "test": "bun test tests/static/",
16 + "test:integration": "bun test tests/integration/ --timeout 30000"
17 },
18 "dependencies": {
19 "@radix-ui/react-tabs": "^1.1.13",
docs/tests/integration/helpers.ts new
+43
@@ -0,0 +1,43 @@
1 +/** Shared helpers for integration tests that hit the running dev/prod server. */
2 +
3 +export const BASE_URL = process.env.TEST_BASE_URL || "http://localhost:3000";
4 +
5 +/** Fetch a URL from the docs server with a timeout */
6 +export async function fetchPage(
7 + path: string,
8 + options?: RequestInit & { timeout?: number }
9 +): Promise<Response> {
10 + const { timeout = 10_000, ...fetchOpts } = options || {};
11 + const controller = new AbortController();
12 + const timer = setTimeout(() => controller.abort(), timeout);
13 +
14 + try {
15 + return await fetch(`${BASE_URL}${path}`, {
16 + ...fetchOpts,
17 + signal: controller.signal,
18 + redirect: "follow",
19 + });
20 + } finally {
21 + clearTimeout(timer);
22 + }
23 +}
24 +
25 +/** Fetch without following redirects to inspect redirect behavior */
26 +export async function fetchNoRedirect(
27 + path: string,
28 + options?: RequestInit & { timeout?: number }
29 +): Promise<Response> {
30 + const { timeout = 10_000, ...fetchOpts } = options || {};
31 + const controller = new AbortController();
32 + const timer = setTimeout(() => controller.abort(), timeout);
33 +
34 + try {
35 + return await fetch(`${BASE_URL}${path}`, {
36 + ...fetchOpts,
37 + signal: controller.signal,
38 + redirect: "manual",
39 + });
40 + } finally {
41 + clearTimeout(timer);
42 + }
43 +}
docs/tests/integration/llm-endpoints.test.ts new
+79
@@ -0,0 +1,79 @@
1 +/**
2 + * LLM endpoint integration tests.
3 + *
4 + * Validates that .md endpoints return well-formed markdown with proper
5 + * content-type headers and guardrails.
6 + */
7 +import { describe, test, expect } from "bun:test";
8 +import { fetchPage } from "./helpers";
9 +
10 +describe("LLM endpoints - llms.txt", () => {
11 + test("/llms.txt returns 200 with text content", async () => {
12 + const res = await fetchPage("/llms.txt");
13 + expect(res.status).toBe(200);
14 +
15 + const text = await res.text();
16 + expect(text.length).toBeGreaterThan(100);
17 + // Should contain page links
18 + expect(text).toContain("composio");
19 + });
20 +});
21 +
22 +describe("LLM endpoints - .md pages", () => {
23 + const MD_PAGES = [
24 + { path: "/docs/quickstart.md", name: "Quickstart" },
25 + { path: "/docs/authentication.md", name: "Authentication" },
26 + { path: "/docs/tools-and-toolkits.md", name: "Tools & Toolkits" },
27 + ];
28 +
29 + for (const { path, name } of MD_PAGES) {
30 + test(`${name} (${path}) returns markdown`, async () => {
31 + const res = await fetchPage(path);
32 + expect(res.status).toBe(200);
33 +
34 + const contentType = res.headers.get("content-type") || "";
35 + expect(contentType).toContain("text/markdown");
36 + });
37 +
38 + test(`${name} (${path}) has a title heading`, async () => {
39 + const res = await fetchPage(path);
40 + const text = await res.text();
41 + // Should start with a markdown heading
42 + expect(text).toMatch(/^#\s+.+/);
43 + });
44 +
45 + test(`${name} (${path}) has meaningful content (> 200 chars)`, async () => {
46 + const res = await fetchPage(path);
47 + const text = await res.text();
48 + expect(text.length).toBeGreaterThan(200);
49 + });
50 + }
51 +});
52 +
53 +describe("LLM endpoints - guardrails", () => {
54 + test("quickstart.md includes guardrail content", async () => {
55 + const res = await fetchPage("/docs/quickstart.md");
56 + const text = await res.text();
57 + // Default guardrails should be appended (session-based pattern)
58 + // The exact content varies but should include the footer
59 + expect(text).toContain("More documentation");
60 + });
61 +});
62 +
63 +describe("LLM endpoints - toolkit markdown", () => {
64 + test("/toolkits.md returns toolkit index", async () => {
65 + const res = await fetchPage("/toolkits.md");
66 + expect(res.status).toBe(200);
67 +
68 + const text = await res.text();
69 + expect(text).toContain("Toolkits");
70 + expect(text.toLowerCase()).toContain("github");
71 + });
72 +});
73 +
74 +describe("LLM endpoints - error handling", () => {
75 + test("non-existent .md page returns 404", async () => {
76 + const res = await fetchPage("/docs/nonexistent-page-xyz.md");
77 + expect(res.status).toBe(404);
78 + });
79 +});
docs/tests/integration/redirects.test.ts new
+59
@@ -0,0 +1,59 @@
1 +/**
2 + * Redirect integration tests.
3 + *
4 + * Validates that key redirect patterns work correctly — old URLs redirect
5 + * to valid destinations that return 200.
6 + */
7 +import { describe, test, expect } from "bun:test";
8 +import { fetchPage, fetchNoRedirect, BASE_URL } from "./helpers";
9 +
10 +/** Sample of important redirects to test (from next.config.mjs) */
11 +const REDIRECTS = [
12 + { from: "/", to: "/docs" },
13 + { from: "/examples", to: "/cookbooks" },
14 + { from: "/api-reference", to: "/reference" },
15 + { from: "/providers/openai", to: "/docs/providers/openai" },
16 + { from: "/providers/anthropic", to: "/docs/providers/anthropic" },
17 + { from: "/tools", to: "/toolkits" },
18 + { from: "/docs/fetching-tools", to: "/docs/tools-direct/fetching-tools" },
19 + { from: "/docs/custom-tools", to: "/docs/tools-direct/custom-tools" },
20 + { from: "/docs/how-tools-work", to: "/docs/tools-and-toolkits" },
21 + { from: "/authentication", to: "/docs/authentication" },
22 + { from: "/changelog", to: "/docs/changelog" },
23 + { from: "/docs/mcp-quickstart", to: "/docs/single-toolkit-mcp" },
24 + { from: "/docs/welcome", to: "/docs" },
25 + { from: "/docs/managed-authentication", to: "/docs/authentication" },
26 +];
27 +
28 +describe("Redirects - key patterns", () => {
29 + for (const { from, to } of REDIRECTS) {
30 + test(`${from} → ${to}`, async () => {
31 + const res = await fetchNoRedirect(from);
32 + // Should be a 301 or 308 redirect
33 + expect([301, 302, 307, 308]).toContain(res.status);
34 +
35 + const location = res.headers.get("location") || "";
36 + // Location might be absolute or relative
37 + const normalizedLocation = location
38 + .replace(BASE_URL, "")
39 + .split("?")[0]; // Strip query params
40 + expect(normalizedLocation).toBe(to);
41 + });
42 + }
43 +});
44 +
45 +describe("Redirects - destinations are valid", () => {
46 + test("all redirect destinations return 200", async () => {
47 + const destinations = [...new Set(REDIRECTS.map((r) => r.to))];
48 + const failures: string[] = [];
49 +
50 + for (const dest of destinations) {
51 + const res = await fetchPage(dest);
52 + if (res.status !== 200) {
53 + failures.push(`${dest} returned ${res.status}`);
54 + }
55 + }
56 +
57 + expect(failures).toEqual([]);
58 + });
59 +});
docs/tests/integration/rendering.test.ts new
+64
@@ -0,0 +1,64 @@
1 +/**
2 + * Page rendering integration tests.
3 + *
4 + * Validates that critical pages render successfully (200), return HTML,
5 + * and contain expected content markers.
6 + */
7 +import { describe, test, expect } from "bun:test";
8 +import { fetchPage } from "./helpers";
9 +
10 +/** Critical pages that must always render */
11 +const CRITICAL_PAGES = [
12 + { path: "/docs", name: "Docs home" },
13 + { path: "/docs/quickstart", name: "Quickstart" },
14 + { path: "/docs/authentication", name: "Authentication" },
15 + { path: "/docs/tools-and-toolkits", name: "Tools & Toolkits" },
16 + { path: "/docs/users-and-sessions", name: "Users & Sessions" },
17 + { path: "/cookbooks", name: "Cookbooks index" },
18 + { path: "/toolkits", name: "Toolkits index" },
19 + { path: "/reference", name: "Reference index" },
20 +];
21 +
22 +describe("Page rendering - critical pages", () => {
23 + for (const { path, name } of CRITICAL_PAGES) {
24 + test(`${name} (${path}) returns 200`, async () => {
25 + const res = await fetchPage(path);
26 + expect(res.status).toBe(200);
27 + });
28 +
29 + test(`${name} (${path}) returns HTML`, async () => {
30 + const res = await fetchPage(path);
31 + const contentType = res.headers.get("content-type") || "";
32 + expect(contentType).toContain("text/html");
33 + });
34 + }
35 +});
36 +
37 +describe("Page rendering - content markers", () => {
38 + test("docs home contains navigation elements", async () => {
39 + const res = await fetchPage("/docs");
40 + const html = await res.text();
41 + // Should have some sidebar/nav content
42 + expect(html).toContain("Quickstart");
43 + });
44 +
45 + test("quickstart page contains expected content", async () => {
46 + const res = await fetchPage("/docs/quickstart");
47 + const html = await res.text();
48 + expect(html.toLowerCase()).toContain("composio");
49 + });
50 +
51 + test("toolkits page renders toolkit cards", async () => {
52 + const res = await fetchPage("/toolkits");
53 + const html = await res.text();
54 + // Should contain at least one well-known toolkit
55 + expect(html.toLowerCase()).toContain("github");
56 + });
57 +});
58 +
59 +describe("Page rendering - error handling", () => {
60 + test("non-existent page returns 404", async () => {
61 + const res = await fetchPage("/docs/this-page-does-not-exist-ever");
62 + expect(res.status).toBe(404);
63 + });
64 +});
docs/tests/integration/search.test.ts new
+55
@@ -0,0 +1,55 @@
1 +/**
2 + * Search API integration tests.
3 + *
4 + * Validates that the search endpoint returns relevant results for key terms.
5 + */
6 +import { describe, test, expect } from "bun:test";
7 +import { fetchPage } from "./helpers";
8 +
9 +describe("Search API", () => {
10 + test("returns results for 'authentication'", async () => {
11 + const res = await fetchPage("/api/search?query=authentication");
12 + expect(res.status).toBe(200);
13 +
14 + const data = await res.json();
15 + expect(Array.isArray(data)).toBe(true);
16 + expect(data.length).toBeGreaterThan(0);
17 +
18 + // At least one result should have a URL and title
19 + const first = data[0];
20 + expect(first).toHaveProperty("url");
21 + expect(first).toHaveProperty("content");
22 + });
23 +
24 + test("returns results for 'quickstart'", async () => {
25 + const res = await fetchPage("/api/search?query=quickstart");
26 + expect(res.status).toBe(200);
27 +
28 + const data = await res.json();
29 + expect(data.length).toBeGreaterThan(0);
30 + });
31 +
32 + test("returns results for 'tools'", async () => {
33 + const res = await fetchPage("/api/search?query=tools");
34 + expect(res.status).toBe(200);
35 +
36 + const data = await res.json();
37 + expect(data.length).toBeGreaterThan(0);
38 + });
39 +
40 + test("returns empty array for nonsense query", async () => {
41 + const res = await fetchPage("/api/search?query=xyzzy123nonexistent");
42 + expect(res.status).toBe(200);
43 +
44 + const data = await res.json();
45 + expect(Array.isArray(data)).toBe(true);
46 + // Should return no results (or very few) for gibberish
47 + expect(data.length).toBeLessThan(3);
48 + });
49 +
50 + test("returns 400 or empty for missing query", async () => {
51 + const res = await fetchPage("/api/search");
52 + // Fumadocs returns 400 for missing query param
53 + expect([200, 400]).toContain(res.status);
54 + });
55 +});
docs/tests/static/content.test.ts new
+159
@@ -0,0 +1,159 @@
1 +/**
2 + * Content validation tests.
3 + *
4 + * Checks that all MDX pages have required frontmatter (title), are non-empty,
5 + * and changelog entries use valid date formats.
6 + */
7 +import { describe, test, expect } from "bun:test";
8 +import { readdir, readFile, stat } from "fs/promises";
9 +import { join, relative } from "path";
10 +
11 +const DOCS_DIR = join(import.meta.dir, "../../content/docs");
12 +const COOKBOOKS_DIR = join(import.meta.dir, "../../content/cookbooks");
13 +const CHANGELOG_DIR = join(import.meta.dir, "../../content/changelog");
14 +
15 +/** Recursively find all .mdx files */
16 +async function findMdxFiles(dir: string): Promise<string[]> {
17 + const results: string[] = [];
18 + let entries;
19 + try {
20 + entries = await readdir(dir, { withFileTypes: true });
21 + } catch {
22 + return results;
23 + }
24 +
25 + for (const entry of entries) {
26 + const fullPath = join(dir, entry.name);
27 + if (entry.isDirectory()) {
28 + results.push(...(await findMdxFiles(fullPath)));
29 + } else if (entry.name.endsWith(".mdx")) {
30 + results.push(fullPath);
31 + }
32 + }
33 + return results;
34 +}
35 +
36 +/** Extract frontmatter from MDX content */
37 +function parseFrontmatter(content: string): Record<string, string> | null {
38 + const match = content.match(/^---\n([\s\S]*?)\n---/);
39 + if (!match) return null;
40 +
41 + const fm: Record<string, string> = {};
42 + for (const line of match[1].split("\n")) {
43 + const colonIdx = line.indexOf(":");
44 + if (colonIdx > 0) {
45 + const key = line.slice(0, colonIdx).trim();
46 + const value = line.slice(colonIdx + 1).trim();
47 + fm[key] = value;
48 + }
49 + }
50 + return fm;
51 +}
52 +
53 +describe("Content - frontmatter validation", () => {
54 + test("all docs pages have a title", async () => {
55 + const files = await findMdxFiles(DOCS_DIR);
56 + const missingTitle: string[] = [];
57 +
58 + for (const file of files) {
59 + const content = await readFile(file, "utf-8");
60 + const fm = parseFrontmatter(content);
61 + if (!fm || !fm.title) {
62 + missingTitle.push(relative(DOCS_DIR, file));
63 + }
64 + }
65 +
66 + expect(missingTitle).toEqual([]);
67 + });
68 +
69 + test("all cookbooks pages have a title", async () => {
70 + const files = await findMdxFiles(COOKBOOKS_DIR);
71 + const missingTitle: string[] = [];
72 +
73 + for (const file of files) {
74 + const content = await readFile(file, "utf-8");
75 + const fm = parseFrontmatter(content);
76 + if (!fm || !fm.title) {
77 + missingTitle.push(relative(COOKBOOKS_DIR, file));
78 + }
79 + }
80 +
81 + expect(missingTitle).toEqual([]);
82 + });
83 +});
84 +
85 +describe("Content - no empty pages", () => {
86 + test("docs pages have meaningful content (> 50 chars after frontmatter)", async () => {
87 + const files = await findMdxFiles(DOCS_DIR);
88 + const empty: string[] = [];
89 +
90 + for (const file of files) {
91 + const content = await readFile(file, "utf-8");
92 + // Strip frontmatter
93 + const body = content.replace(/^---[\s\S]*?---\n*/, "").trim();
94 + if (body.length < 50) {
95 + empty.push(relative(DOCS_DIR, file));
96 + }
97 + }
98 +
99 + expect(empty).toEqual([]);
100 + });
101 +});
102 +
103 +describe("Content - changelog validation", () => {
104 + test("changelog files use MM-DD-YY naming pattern", async () => {
105 + let entries;
106 + try {
107 + entries = await readdir(CHANGELOG_DIR);
108 + } catch {
109 + return;
110 + }
111 +
112 + // Files are named MM-DD-YY.mdx or MM-DD-YY-description.mdx
113 + const nameRegex = /^\d{2}-\d{2}-\d{2}(-[\w-]+)?\.mdx$/;
114 + const invalid: string[] = [];
115 +
116 + for (const entry of entries) {
117 + if (entry === "meta.json" || entry === ".DS_Store") continue;
118 + if (!nameRegex.test(entry)) {
119 + invalid.push(entry);
120 + }
121 + }
122 +
123 + expect(invalid).toEqual([]);
124 + });
125 +
126 + test("changelog entries have a title and valid YYYY-MM-DD date in frontmatter", async () => {
127 + let entries;
128 + try {
129 + entries = await readdir(CHANGELOG_DIR);
130 + } catch {
131 + return;
132 + }
133 +
134 + const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
135 + const errors: string[] = [];
136 +
137 + for (const entry of entries) {
138 + if (!entry.endsWith(".mdx")) continue;
139 + const content = await readFile(join(CHANGELOG_DIR, entry), "utf-8");
140 + const fm = parseFrontmatter(content);
141 +
142 + if (!fm || !fm.title) {
143 + errors.push(`${entry}: missing title`);
144 + }
145 +
146 + const dateValue = fm?.date?.replace(/["']/g, "");
147 + if (!dateValue || !dateRegex.test(dateValue)) {
148 + errors.push(`${entry}: missing or invalid date (expected YYYY-MM-DD)`);
149 + } else {
150 + const parsed = new Date(`${dateValue}T12:00:00`);
151 + if (isNaN(parsed.getTime())) {
152 + errors.push(`${entry}: date "${dateValue}" is not a valid calendar date`);
153 + }
154 + }
155 + }
156 +
157 + expect(errors).toEqual([]);
158 + });
159 +});
docs/tests/static/navigation.test.ts new
+151
@@ -0,0 +1,151 @@
1 +/**
2 + * Navigation completeness tests.
3 + *
4 + * Validates that every entry in meta.json files maps to a real .mdx file or
5 + * directory, and that every content file is referenced in its parent meta.json.
6 + */
7 +import { describe, test, expect } from "bun:test";
8 +import { readdir, readFile, stat } from "fs/promises";
9 +import { join, basename, dirname, relative } from "path";
10 +
11 +const CONTENT_DIR = join(import.meta.dir, "../../content/docs");
12 +
13 +/** Separator entries in meta.json start with --- */
14 +function isSeparator(entry: string): boolean {
15 + return entry.startsWith("---");
16 +}
17 +
18 +/** Recursively find all meta.json files under a directory */
19 +async function findMetaFiles(dir: string): Promise<string[]> {
20 + const results: string[] = [];
21 + const entries = await readdir(dir, { withFileTypes: true });
22 +
23 + for (const entry of entries) {
24 + const fullPath = join(dir, entry.name);
25 + if (entry.isDirectory()) {
26 + results.push(...(await findMetaFiles(fullPath)));
27 + } else if (entry.name === "meta.json") {
28 + results.push(fullPath);
29 + }
30 + }
31 + return results;
32 +}
33 +
34 +/** Check if a path exists as a file or directory */
35 +async function exists(path: string): Promise<boolean> {
36 + try {
37 + await stat(path);
38 + return true;
39 + } catch {
40 + return false;
41 + }
42 +}
43 +
44 +describe("Navigation - meta.json validity", () => {
45 + test("root meta.json entries all resolve to files or directories", async () => {
46 + const metaPath = join(CONTENT_DIR, "meta.json");
47 + const meta = JSON.parse(await readFile(metaPath, "utf-8"));
48 + const missing: string[] = [];
49 +
50 + for (const entry of meta.pages as string[]) {
51 + if (isSeparator(entry)) continue;
52 +
53 + const asFile = join(CONTENT_DIR, `${entry}.mdx`);
54 + const asDir = join(CONTENT_DIR, entry);
55 +
56 + const fileExists = await exists(asFile);
57 + const dirExists = await exists(asDir);
58 +
59 + if (!fileExists && !dirExists) {
60 + missing.push(entry);
61 + }
62 + }
63 +
64 + expect(missing).toEqual([]);
65 + });
66 +
67 + test("all nested meta.json entries resolve to files or directories", async () => {
68 + const metaFiles = await findMetaFiles(CONTENT_DIR);
69 + const errors: string[] = [];
70 +
71 + for (const metaPath of metaFiles) {
72 + const dir = dirname(metaPath);
73 + const meta = JSON.parse(await readFile(metaPath, "utf-8"));
74 + const relDir = relative(CONTENT_DIR, dir);
75 +
76 + for (const entry of (meta.pages || []) as string[]) {
77 + if (isSeparator(entry)) continue;
78 +
79 + // Handle "..." (rest) entries which are valid fumadocs syntax
80 + if (entry === "...") continue;
81 +
82 + const asFile = join(dir, `${entry}.mdx`);
83 + const asDir = join(dir, entry);
84 +
85 + const fileExists = await exists(asFile);
86 + const dirExists = await exists(asDir);
87 +
88 + if (!fileExists && !dirExists) {
89 + errors.push(`${relDir}/meta.json → "${entry}" (no .mdx file or directory found)`);
90 + }
91 + }
92 + }
93 +
94 + expect(errors).toEqual([]);
95 + });
96 +
97 + test("no orphan .mdx files missing from meta.json", async () => {
98 + const metaFiles = await findMetaFiles(CONTENT_DIR);
99 + const orphans: string[] = [];
100 +
101 + // Check root level
102 + const rootMetaPath = join(CONTENT_DIR, "meta.json");
103 + const rootMeta = JSON.parse(await readFile(rootMetaPath, "utf-8"));
104 + const rootEntries = new Set(
105 + (rootMeta.pages as string[]).filter((e: string) => !isSeparator(e))
106 + );
107 + const rootFiles = await readdir(CONTENT_DIR, { withFileTypes: true });
108 +
109 + for (const file of rootFiles) {
110 + if (file.name === "meta.json") continue;
111 + const name = file.isFile() ? basename(file.name, ".mdx") : file.name;
112 + if (file.isFile() && !file.name.endsWith(".mdx")) continue;
113 + if (!rootEntries.has(name)) {
114 + orphans.push(`docs/${file.name}`);
115 + }
116 + }
117 +
118 + // Check each nested directory that has a meta.json
119 + for (const metaPath of metaFiles) {
120 + if (metaPath === rootMetaPath) continue;
121 + const dir = dirname(metaPath);
122 + const meta = JSON.parse(await readFile(metaPath, "utf-8"));
123 + const entries = new Set(
124 + ((meta.pages || []) as string[]).filter((e: string) => !isSeparator(e))
125 + );
126 + // "..." means "include everything else", so skip orphan check
127 + if (entries.has("...")) continue;
128 +
129 + const files = await readdir(dir, { withFileTypes: true });
130 + const relDir = relative(CONTENT_DIR, dir);
131 +
132 + for (const file of files) {
133 + if (file.name === "meta.json") continue;
134 + const name = file.isFile() ? basename(file.name, ".mdx") : file.name;
135 + if (file.isFile() && !file.name.endsWith(".mdx")) continue;
136 + if (!entries.has(name)) {
137 + orphans.push(`${relDir}/${file.name}`);
138 + }
139 + }
140 + }
141 +
142 + if (orphans.length > 0) {
143 + console.warn(
144 + `Found ${orphans.length} orphan file(s) not in any meta.json:\n` +
145 + orphans.map((o) => ` - ${o}`).join("\n")
146 + );
147 + }
148 + // Warn but don't fail — orphans aren't necessarily bugs
149 + expect(orphans.length).toBeLessThan(20);
150 + });
151 +});
docs/tests/static/toolkit-data.test.ts new
+104
@@ -0,0 +1,104 @@
1 +/**
2 + * Toolkit data integrity tests.
3 + *
4 + * Validates that toolkits.json and toolkits-list.json exist, are valid JSON,
5 + * and contain the expected structure.
6 + */
7 +import { describe, test, expect } from "bun:test";
8 +import { readFile } from "fs/promises";
9 +import { join } from "path";
10 +
11 +const DATA_DIR = join(import.meta.dir, "../../public/data");
12 +
13 +interface ToolkitListItem {
14 + slug: string;
15 + name: string;
16 + logo: string;
17 + category: string;
18 + toolCount: number;
19 + triggerCount: number;
20 +}
21 +
22 +interface ToolkitFull extends ToolkitListItem {
23 + description: string;
24 + authSchemes: string[];
25 + tools: Array<{ slug: string; name: string; description: string }>;
26 +}
27 +
28 +describe("Toolkit data - toolkits.json", () => {
29 + let data: ToolkitFull[];
30 +
31 + test("file exists and is valid JSON", async () => {
32 + const raw = await readFile(join(DATA_DIR, "toolkits.json"), "utf-8");
33 + data = JSON.parse(raw);
34 + expect(Array.isArray(data)).toBe(true);
35 + });
36 +
37 + test("has a reasonable number of toolkits (> 50)", () => {
38 + expect(data.length).toBeGreaterThan(50);
39 + });
40 +
41 + test("each toolkit has required fields", () => {
42 + const invalid: string[] = [];
43 +
44 + for (const toolkit of data) {
45 + if (!toolkit.slug || typeof toolkit.slug !== "string") {
46 + invalid.push(`missing slug: ${JSON.stringify(toolkit).slice(0, 80)}`);
47 + continue;
48 + }
49 + if (!toolkit.name || typeof toolkit.name !== "string") {
50 + invalid.push(`${toolkit.slug}: missing name`);
51 + }
52 + if (typeof toolkit.toolCount !== "number") {
53 + invalid.push(`${toolkit.slug}: missing toolCount`);
54 + }
55 + if (!Array.isArray(toolkit.authSchemes)) {
56 + invalid.push(`${toolkit.slug}: missing authSchemes array`);
57 + }
58 + }
59 +
60 + expect(invalid).toEqual([]);
61 + });
62 +
63 + test("no duplicate slugs", () => {
64 + const slugs = data.map((t) => t.slug);
65 + const duplicates = slugs.filter((s, i) => slugs.indexOf(s) !== i);
66 + expect(duplicates).toEqual([]);
67 + });
68 +
69 + test("well-known toolkits exist", () => {
70 + const slugs = new Set(data.map((t) => t.slug));
71 + const expected = ["github", "gmail", "slack", "notion"];
72 + const missing = expected.filter((s) => !slugs.has(s));
73 + expect(missing).toEqual([]);
74 + });
75 +});
76 +
77 +describe("Toolkit data - toolkits-list.json", () => {
78 + let data: ToolkitListItem[];
79 +
80 + test("file exists and is valid JSON", async () => {
81 + const raw = await readFile(join(DATA_DIR, "toolkits-list.json"), "utf-8");
82 + data = JSON.parse(raw);
83 + expect(Array.isArray(data)).toBe(true);
84 + });
85 +
86 + test("list count matches full data count", async () => {
87 + const fullRaw = await readFile(join(DATA_DIR, "toolkits.json"), "utf-8");
88 + const full = JSON.parse(fullRaw);
89 + expect(data.length).toBe(full.length);
90 + });
91 +
92 + test("each entry has required list fields", () => {
93 + const invalid: string[] = [];
94 +
95 + for (const item of data) {
96 + if (!item.slug) invalid.push("missing slug");
97 + if (!item.name) invalid.push(`${item.slug}: missing name`);
98 + if (typeof item.toolCount !== "number")
99 + invalid.push(`${item.slug}: missing toolCount`);
100 + }
101 +
102 + expect(invalid).toEqual([]);
103 + });
104 +});