fix(docs-test): Windows venvs and failing TypeScript examples (#1804)

Community fixes for the docs-test runner.

- Python examples run on Windows: the runner picks `.venv/Scripts/python.exe` and reports a missing venv as a failed test (#1487).
- TypeScript examples exit 1 when `main()` rejects, so broken examples no longer count as passed (#1495).

Co-Authored-By: abhinav7x94 <204053250+abhinav7x94@users.noreply.github.com>

packages/docs-test/run.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
-import { spawn } from "child_process"
-import path from "path"
+import { spawn } from "node:child_process"
+import path from "node:path"
 
 const args = process.argv.slice(2)
 const filter = args[0] // e.g., "typescript", "python", "integrations", or specific file
@@ -13,6 +13,15 @@ interface TestFile {
 	type: "ts" | "py"
 }
 
+export function getPythonExecutable(
+	platform = process.platform,
+	baseDir = import.meta.dir,
+): string {
+	return platform === "win32"
+		? path.join(baseDir, ".venv", "Scripts", "python.exe")
+		: path.join(baseDir, ".venv", "bin", "python3")
+}
+
 function getTests(): TestFile[] {
 	const tests: TestFile[] = []
 
@@ -64,16 +73,24 @@ async function runTest(test: TestFile): Promise<boolean> {
 		console.log(`Running: ${test.name}`)
 		console.log("=".repeat(60))
 
-		const cmd =
-			test.type === "ts"
-				? "bun"
-				: path.join(import.meta.dir, ".venv", "bin", "python3")
+		const cmd = test.type === "ts" ? "bun" : getPythonExecutable()
 		const proc = spawn(cmd, [test.path], {
 			stdio: "inherit",
 			env: { ...process.env },
 		})
 
-		proc.on("close", (code) => {
+		proc.once("error", (error) => {
+			console.error(`Failed to start ${test.name}: ${error.message}`)
+			if (test.type === "py" && "code" in error && error.code === "ENOENT") {
+				console.error(`Expected Python executable at: ${cmd}`)
+				console.error(
+					'Create it with "python -m venv .venv" and install requirements.txt.',
+				)
+			}
+			resolve(false)
+		})
+
+		proc.once("close", (code) => {
 			resolve(code === 0)
 		})
 	})
@@ -95,7 +112,9 @@ async function main() {
 	if (tests.length === 0) {
 		console.log("No tests matched the filter:", filter)
 		console.log("\nAvailable tests:")
-		getTests().forEach((t) => console.log(`  - ${t.name} (${t.type})`))
+		getTests().forEach((t) => {
+			console.log(`  - ${t.name} (${t.type})`)
+		})
 		process.exit(1)
 	}
 
@@ -127,4 +146,9 @@ async function main() {
 	}
 }
 
-main().catch(console.error)
+if (import.meta.main) {
+	main().catch((error) => {
+		console.error(error)
+		process.exitCode = 1
+	})
+}

packages/docs-test/tests/integrations/ai-sdk.ts

@@ -13,14 +13,14 @@ async function testMiddleware() {
 	console.log("=== Middleware ===")
 
 	// Basic wrapper
-	const model = withSupermemory(openai("gpt-4"), {
+	const _model = withSupermemory(openai("gpt-4"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 	})
 	console.log("✓ withSupermemory basic")
 
 	// With addMemory option
-	const modelWithAdd = withSupermemory(openai("gpt-4"), {
+	const _modelWithAdd = withSupermemory(openai("gpt-4"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 		addMemory: "always",
@@ -28,7 +28,7 @@ async function testMiddleware() {
 	console.log("✓ withSupermemory with addMemory")
 
 	// With verbose logging
-	const modelVerbose = withSupermemory(openai("gpt-4"), {
+	const _modelVerbose = withSupermemory(openai("gpt-4"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 		verbose: true,
@@ -39,21 +39,21 @@ async function testMiddleware() {
 async function testSearchModes() {
 	console.log("\n=== Search Modes ===")
 
-	const profileModel = withSupermemory(openai("gpt-4"), {
+	const _profileModel = withSupermemory(openai("gpt-4"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 		mode: "profile",
 	})
 	console.log("✓ mode: profile")
 
-	const queryModel = withSupermemory(openai("gpt-4"), {
+	const _queryModel = withSupermemory(openai("gpt-4"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 		mode: "query",
 	})
 	console.log("✓ mode: query")
 
-	const fullModel = withSupermemory(openai("gpt-4"), {
+	const _fullModel = withSupermemory(openai("gpt-4"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 		mode: "full",
@@ -74,7 +74,7 @@ async function testCustomPrompt() {
 </context>
 `.trim()
 
-	const model = withSupermemory(anthropic("claude-3-sonnet-20240229"), {
+	const _model = withSupermemory(anthropic("claude-3-sonnet-20240229"), {
 		containerTag: "user-123",
 		customId: "conv-1",
 		mode: "full",
@@ -87,7 +87,7 @@ async function testTools() {
 	console.log("\n=== Memory Tools ===")
 
 	// All tools
-	const tools = supermemoryTools("YOUR_API_KEY")
+	const _tools = supermemoryTools("YOUR_API_KEY")
 	console.log("✓ supermemoryTools")
 
 	// Individual tools
@@ -98,7 +98,7 @@ async function testTools() {
 	console.log("✓ addMemoryTool")
 
 	// Combined
-	const toolsObj = {
+	const _toolsObj = {
 		searchMemories: searchTool,
 		addMemory: addTool,
 	}
@@ -118,4 +118,7 @@ async function main() {
 	console.log("✅ All AI SDK tests passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})

packages/docs-test/tests/integrations/claude-memory.ts

@@ -11,7 +11,7 @@ async function testConfiguration() {
 	console.log("✓ Basic config")
 
 	// Full options
-	const toolFull = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, {
+	const _toolFull = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, {
 		projectId: "my-app",
 		containerTags: ["user-123", "project-alpha"],
 		memoryContainerTag: "my_memory_prefix",
@@ -102,4 +102,7 @@ async function main() {
 	console.log("✅ All Claude Memory tests passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})

packages/docs-test/tests/integrations/openai-sdk.ts

@@ -15,11 +15,11 @@ async function testOpenAIWrapper() {
 	const openai = new OpenAI()
 
 	// Basic wrapper
-	const client = withSupermemory(openai, "docs-test-openai")
+	const _client = withSupermemory(openai, "docs-test-openai")
 	console.log("✓ withSupermemory basic")
 
 	// With options
-	const clientWithOptions = withSupermemory(openai, "docs-test-openai", {
+	const _clientWithOptions = withSupermemory(openai, "docs-test-openai", {
 		mode: "full",
 		addMemory: "always",
 		verbose: true,
@@ -83,4 +83,7 @@ async function main() {
 	console.log("✅ All OpenAI SDK tests passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})

packages/docs-test/tests/typescript/quickstart.ts

@@ -20,7 +20,7 @@ async function main() {
 	console.log("1. Getting user profile...")
 	const profile = await client.profile({
 		containerTag: USER_ID,
-		q: conversation.at(-1)!.content,
+		q: conversation.at(-1)?.content,
 	})
 
 	console.log("Profile response:", JSON.stringify(profile, null, 2))
@@ -37,7 +37,7 @@ ${profile.searchResults?.results.map((r) => r.content).join("\n")}`
 	console.log("\n2. Built context:", context)
 
 	// Build messages with memory-enriched context
-	const messages = [
+	const _messages = [
 		{ role: "system", content: `User context:\n${context}` },
 		...conversation,
 	]
@@ -54,4 +54,7 @@ ${profile.searchResults?.results.map((r) => r.content).join("\n")}`
 	console.log("\n✅ Quickstart TypeScript test passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})

packages/docs-test/tests/typescript/sdk.ts

@@ -1,5 +1,5 @@
 import "dotenv/config"
-import fs from "fs"
+import fs from "node:fs"
 import Supermemory, { toFile } from "supermemory"
 
 const client = new Supermemory()
@@ -9,7 +9,7 @@ async function testDocumentsCRUD() {
 
 	// Create
 	const doc = await client.documents.add({
-		content: "Test content for TypeScript SDK - " + Date.now(),
+		content: `Test content for TypeScript SDK - ${Date.now()}`,
 	})
 	console.log("✓ documents.add:", doc.id)
 
@@ -19,7 +19,7 @@ async function testDocumentsCRUD() {
 
 	// Update
 	const updated = await client.documents.update(doc.id, {
-		content: "Updated content - " + Date.now(),
+		content: `Updated content - ${Date.now()}`,
 	})
 	console.log("✓ documents.update:", updated.id)
 
@@ -36,8 +36,8 @@ async function testBatchOperations() {
 
 	const batch = await client.documents.batchAdd({
 		documents: [
-			{ content: "Batch doc 1 - " + Date.now() },
-			{ content: "Batch doc 2 - " + Date.now() },
+			{ content: `Batch doc 1 - ${Date.now()}` },
+			{ content: `Batch doc 2 - ${Date.now()}` },
 		],
 	})
 	console.log("✓ documents.batchAdd:", batch)
@@ -76,16 +76,16 @@ async function testClientConfig() {
 	console.log("\n=== Client Configuration ===")
 
 	// Retries
-	const clientWithRetries = new Supermemory({ maxRetries: 0 })
+	const _clientWithRetries = new Supermemory({ maxRetries: 0 })
 	console.log("✓ maxRetries config")
 
 	// Timeout
-	const clientWithTimeout = new Supermemory({ timeout: 20 * 1000 })
+	const _clientWithTimeout = new Supermemory({ timeout: 20 * 1000 })
 	console.log("✓ timeout config")
 
 	// Per-request options
 	await client.add(
-		{ content: "Test - " + Date.now() },
+		{ content: `Test - ${Date.now()}` },
 		{ maxRetries: 5, timeout: 5000 },
 	)
 	console.log("✓ per-request options")
@@ -95,12 +95,12 @@ async function testRawResponse() {
 	console.log("\n=== Raw Response ===")
 
 	const response = await client.documents
-		.add({ content: "Test - " + Date.now() })
+		.add({ content: `Test - ${Date.now()}` })
 		.asResponse()
 	console.log("✓ .asResponse() status:", response.status)
 
 	const { data, response: raw } = await client.documents
-		.add({ content: "Test - " + Date.now() })
+		.add({ content: `Test - ${Date.now()}` })
 		.withResponse()
 	console.log("✓ .withResponse() data:", data.id, "status:", raw.status)
 }
@@ -119,7 +119,7 @@ async function testErrorHandling() {
 	console.log("\n=== Error Handling ===")
 
 	const response = await client.documents
-		.add({ content: "Test - " + Date.now() })
+		.add({ content: `Test - ${Date.now()}` })
 		.catch(async (err) => {
 			if (err instanceof Supermemory.APIError) {
 				console.log("Caught APIError:", err.status, err.name)
@@ -148,4 +148,7 @@ async function main() {
 	console.log("✅ All TypeScript SDK tests passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})

packages/docs-test/tests/typescript/search.ts

@@ -115,4 +115,7 @@ async function main() {
 	console.log("✅ All search tests passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})

packages/docs-test/tests/typescript/user-profiles.ts

@@ -57,7 +57,7 @@ async function testBuildingContext() {
 
 	const profile = await client.profile({
 		containerTag: USER_ID,
-		q: conversation.at(-1)!.content,
+		q: conversation.at(-1)?.content,
 	})
 
 	const context = `User Profile:
@@ -90,4 +90,7 @@ async function main() {
 	console.log("✅ All user profile tests passed!")
 }
 
-main().catch(console.error)
+main().catch((error) => {
+	console.error(error)
+	process.exitCode = 1
+})