Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 08:15 UTC
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
+});