testing

Author: elithrar

src/content/docs/agents/api-reference/sdk.mdx

@@ -112,7 +112,7 @@ Your own methods can access the Agent's environment variables and bindings on `t
 
 You can create and run an instance of an Agent directly from a Worker in one of three ways:
 
-1. Using the `routeAgentRequest` helper: this will automatically map requests to an individual Agent based on the `/agents/:agent/:name` URL pattern.
+1. Using the `routeAgentRequest` helper: this will automatically map requests to an individual Agent based on the `/agents/:agent/:name` URL pattern. The value of `:agent` will be the name of your Agent class converted to `kebab-case`, and the value of `:name` will be the name of the Agent instance you want to create or retrieve.
 2. Calling `getAgentByName`, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.
 3. The [Durable Objects stub API](/durable-objects/api/id/), which provides a lower level API for creating and retrieving Agents.
 

src/content/docs/agents/getting-started/testing-your-agent.mdx

@@ -8,4 +8,137 @@ sidebar:
 
 import { Render, PackageManagers, WranglerConfig } from "~/components"
 
-TODO
+Because Agents run on Cloudflare Workers and Durable Objects, they can be tested using the same tools and techniques as Workers and Durable Objects.
+
+## Writing and runnning tests
+
+### Setup
+
+:::note
+
+The `@cloudflare/agents-starter` template and new Cloudflare Workers projects already include the relevant `vitest` and `@cloudflare/vitest-pool-workers` packages, as well as a valid `vitest.config.js` file.
+
+:::
+
+Before you write your first test, install the necessary packages:
+
+```sh
+npm install [email protected] --save-dev --save-exact
+npm install @cloudflare/vitest-pool-workers --save-dev
+```
+
+Ensure that your `vitest.config.js` file is identical to the following:
+
+```js
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: {
+      workers: {
+        wrangler: { configPath: "./wrangler.toml" },
+      },
+    },
+  },
+});
+```
+
+### Add the Agent configuration
+
+Add a `durableObjects` configuration to `vitest.config.js` with the name of your Agent class:
+
+```js
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
+
+export default defineWorkersConfig({
+	test: {
+		poolOptions: {
+			workers: {
+				main: './src/index.ts',
+				miniflare: {
+					durableObjects: {
+						NAME: 'MyAgent',
+					},
+				},
+			},
+		},
+	},
+});
+```
+
+### Write a test
+
+:::note
+
+Review the [Vitest documentation](https://vitest.dev/) for more information on testing, including the test API reference and advanced testing techniques.
+
+:::
+
+Tests use the `vitest` framework. A basic test suite for your Agent can validate how your Agent responds to requests, but can also unit test your Agent's methods and state.
+
+```ts
+import { env, createExecutionContext, waitOnExecutionContext, SELF } from 'cloudflare:test';
+import { describe, it, expect } from 'vitest';
+import worker from '../src';
+import { Env } from '../src';
+
+interface ProvidedEnv extends Env {}
+
+describe('make a request to my Agent', () => {
+	// Unit testing approach
+	it('responds with state', async () => {
+		// Provide a valid URL that your Worker can use to route to your Agent
+		// If you are using routeAgentRequest, this will be /agent/:agent/:name
+		const request = new Request<unknown, IncomingRequestCfProperties>('http://example.com/agent/my-agent/agent-123');
+		const ctx = createExecutionContext();
+		const response = await worker.fetch(request, env, ctx);
+		await waitOnExecutionContext(ctx);
+		expect(await response.text()).toMatchObject({ hello: 'from your agent' });
+	});
+
+	it('also responds with state', async () => {
+		const request = new Request('http://example.com/agent/my-agent/agent-123');
+		const response = await SELF.fetch(request);
+		expect(await response.text()).toMatchObject({ hello: 'from your agent' });
+	});
+});
+```
+
+### Run tests
+
+Running tests is done using the `vitest` CLI:
+
+```sh
+$ npm run test
+# or run vitest directly
+$ npx vitest
+```
+```sh output
+  MyAgent
+    ✓ should return a greeting (1 ms)
+
+Test Files  1 passed (1)
+```
+
+Review the [documentation on testing](/workers/testing/vitest-integration/get-started/write-your-first-test/) for additional examples and test configuration.
+
+## Running Agents locally
+
+You can also run an Agent locally using the `wrangler` CLI:
+
+```sh
+$ npx wrangler dev
+```
+```sh output
+Your Worker and resources are simulated locally via Miniflare. For more information, see: https://developers.cloudflare.com/workers/testing/local-development.
+
+Your worker has access to the following bindings:
+- Durable Objects:
+  - MyAgent: MyAgent
+  Starting local server...
+[wrangler:inf] Ready on http://localhost:53645
+```
+
+This spins up a local development server that runs the same runtime as Cloudflare Workers, and allows you to iterate on your Agent's code and test it locally without deploying it.
+
+Visit the [`wrangler dev`](https://developers.cloudflare.com/workers/wrangler/commands/#dev) docs to review the CLI flags and configuration options.

src/content/docs/agents/getting-started/writing-your-first-agent.mdx

@@ -6,7 +6,7 @@ sidebar:
 
 ---
 
-import { Render, PackageManagers, WranglerConfig } from "~/components"
+import { Render, PackageManagers, TypeScriptExample, WranglerConfig } from "~/components"
 
 :::note