Add testing utilities documentation for PR #666

Synced from cloudflare/agents PR #666
cloudflare/agents#666

Author: github-actions[bot]

src/content/docs/agents/api-reference/testing-utilities.mdx

@@ -0,0 +1,113 @@
+---
+title: Testing utilities
+pcx_content_type: concept
+sidebar:
+  order: 12
+---
+
+import { TypeScriptExample } from "~/components";
+
+The Agents SDK provides utilities for testing and validating your Agent implementations.
+
+## Test documentation sync
+
+The `testDocsSync()` function helps validate the automated documentation synchronization workflow between the agents repository and cloudflare-docs.
+
+### Signature
+
+```typescript
+function testDocsSync(options?: TestDocsSyncOptions): TestDocsSyncResult;
+```
+
+### Parameters
+
+- `options` (optional): Configuration options for the test
+  - `message` (string, optional): Custom message to include in the test result
+  - `includeTimestamp` (boolean, optional): Whether to include a timestamp in the result
+
+### Returns
+
+- `TestDocsSyncResult`: Object containing test results
+  - `success` (boolean): Whether the test succeeded
+  - `message` (string): Description of the test result
+  - `timestamp` (number, optional): Unix timestamp when the test was run (if `includeTimestamp` was true)
+
+### Example
+
+<TypeScriptExample>
+
+```ts
+import { testDocsSync } from "@cloudflare/agents";
+
+// Basic usage
+const result = testDocsSync();
+console.log(result.message);
+// Output: "Docs sync test successful: Default test"
+
+// With custom options
+const customResult = testDocsSync({
+  message: "Testing PR #123",
+  includeTimestamp: true
+});
+console.log(customResult.message);
+// Output: "Docs sync test successful: Testing PR #123"
+console.log(customResult.timestamp);
+// Output: 1731974400000
+```
+
+</TypeScriptExample>
+
+## Validate documentation sync bot
+
+The `validateDocsSyncBot()` function validates that the documentation sync bot is configured and working correctly. This is useful in CI/CD pipelines to verify that documentation changes are properly synchronized.
+
+### Signature
+
+```typescript
+function validateDocsSyncBot(): boolean;
+```
+
+### Returns
+
+- `boolean`: `true` if the bot validation passes, `false` otherwise
+
+### Example
+
+<TypeScriptExample>
+
+```ts
+import { validateDocsSyncBot } from "@cloudflare/agents";
+
+if (validateDocsSyncBot()) {
+  console.log("Documentation sync bot is working correctly");
+} else {
+  console.log("Documentation sync bot validation failed");
+}
+```
+
+</TypeScriptExample>
+
+## CI/CD integration
+
+You can use these utilities in your CI/CD pipeline to verify documentation sync:
+
+<TypeScriptExample>
+
+```ts
+import { testDocsSync, validateDocsSyncBot } from "@cloudflare/agents";
+
+// Validate bot configuration
+if (!validateDocsSyncBot()) {
+  throw new Error("Docs sync bot is not configured correctly");
+}
+
+// Run test
+const result = testDocsSync({
+  message: `PR #${process.env.PR_NUMBER}`,
+  includeTimestamp: true
+});
+
+console.log(`Test completed at ${new Date(result.timestamp)}`);
+```
+
+</TypeScriptExample>