docs: add testing docs (#801)

Author: NathanFlurry

docs/changelog/overview.mdx

@@ -9,6 +9,16 @@ mode: "center"
 	Releases](https://github.com/rivet-gg/actor-core/releases) page.
 </Info>
 
+<Update description="0.7.6" label="March 26th, 2025">
+  ## Features
+
+  - [**Testing with Vitest**](/concepts/testing): Write unit tests for your actors with [Vitest](https://vitest.dev/)
+
+  ## Fixes
+
+  - Using `vars` and `state` in the same actor sometimes causes `unknown` types
+</Update>
+
 <Update description="0.7.5" label="March 25th, 2025">
   ## Features
 

docs/concepts/testing.mdx

@@ -0,0 +1,244 @@
+---
+title: Testing
+icon: vial-circle-check
+---
+
+ActorCore provides a straightforward testing framework to build reliable and maintainable applications. This guide covers how to write effective tests for your actor-based services.
+
+## Setup
+
+To set up testing with ActorCore:
+
+```bash
+# Install Vitest
+npm install -D vitest
+
+# Run tests
+npm test
+```
+
+## Basic Testing Setup
+
+ActorCore includes a test helper called `setupTest` that configures a test environment with in-memory drivers for your actors. This allows for fast, isolated tests without external dependencies.
+
+<CodeGroup>
+```ts tests/my-actor.test.ts
+import { test, expect } from "vitest";
+import { setupTest } from "actor-core/test";
+import { app } from "../src/index";
+
+test("my actor test", async () => {
+  const { client } = await setupTest(app);
+  
+  // Now you can interact with your actor through the client
+  const myActor = await client.myActor.get();
+  
+  // Test your actor's functionality
+  await myActor.someAction();
+  
+  // Make assertions
+  const result = await myActor.getState();
+  expect(result).toEqual("updated");
+});
+```
+
+```ts src/index.ts
+import { actor, setup } from "actor-core";
+
+const myActor = actor({
+  state: { value: "initial" },
+  actions: {
+    someAction: (c) => {
+      c.state.value = "updated";
+      return c.state.value;
+    },
+    getState: (c) => {
+      return c.state.value;
+    }
+  }
+});
+
+export const app = setup({
+  actors: { myActor }
+});
+
+export type App = typeof app;
+```
+</CodeGroup>
+
+## Testing Actor State
+
+The test framework uses in-memory drivers that persist state within each test, allowing you to verify that your actor correctly maintains state between operations.
+
+<CodeGroup>
+```ts tests/counter.test.ts
+import { test, expect } from "vitest";
+import { setupTest } from "actor-core/test";
+import { app } from "../src/index";
+
+test("actor should persist state", async () => {
+  const { client } = await setupTest(app);
+  const counter = await client.counter.get();
+  
+  // Initial state
+  expect(await counter.getCount()).toBe(0);
+  
+  // Modify state
+  await counter.increment();
+  
+  // Verify state was updated
+  expect(await counter.getCount()).toBe(1);
+});
+```
+
+```ts src/index.ts
+import { setup } from "actor-core";
+
+const counter = actor({
+  state: { count: 0 },
+  actions: {
+    increment: (c) => {
+      c.state.count += 1;
+      c.broadcast("newCount", c.state.count);
+      return c.state.count;
+    },
+    getCount: (c) => {
+      return c.state.count;
+    }
+  }
+});
+
+export const app = setup({
+  actors: { counter }
+});
+
+export type App = typeof app;
+```
+</CodeGroup>
+
+## Testing Events
+
+For actors that emit events, you can verify events are correctly triggered by subscribing to them:
+
+<CodeGroup>
+```ts tests/chat-room.test.ts
+import { test, expect, vi } from "vitest";
+import { setupTest } from "actor-core/test";
+import { app } from "../src/index";
+
+test("actor should emit events", async () => {
+  const { client } = await setupTest(app);
+  const chatRoom = await client.chatRoom.get();
+  
+  // Set up event handler with a mock function
+  const mockHandler = vi.fn();
+  chatRoom.on("newMessage", mockHandler);
+  
+  // Trigger the event
+  await chatRoom.sendMessage("testUser", "Hello world");
+  
+  // Wait for the event to be emitted
+  await vi.waitFor(() => {
+    expect(mockHandler).toHaveBeenCalledWith("testUser", "Hello world");
+  });
+});
+```
+
+```ts src/index.ts
+import { actor, setup } from "actor-core";
+
+export const chatRoom = actor({
+  state: { 
+    messages: []
+  },
+  actions: {
+    sendMessage: (c, username: string, message: string) => {
+      c.state.messages.push({ username, message });
+      c.broadcast("newMessage", username, message);
+    },
+    getHistory: (c) => {
+      return c.state.messages;
+    },
+  },
+});
+
+// Create and export the app
+export const app = setup({
+  actors: { chatRoom }
+});
+
+// Export type for client type checking
+export type App = typeof app;
+```
+</CodeGroup>
+
+## Testing Schedules
+
+ActorCore's schedule functionality can be tested using Vitest's time manipulation utilities:
+
+<CodeGroup>
+```ts tests/scheduler.test.ts
+import { test, expect, vi } from "vitest";
+import { setupTest } from "actor-core/test";
+import { app } from "../src/index";
+
+test("scheduled tasks should execute", async () => {
+  // setupTest automatically configures vi.useFakeTimers()
+  const { client } = await setupTest(app);
+  const scheduler = await client.scheduler.get();
+  
+  // Set up a scheduled task
+  await scheduler.scheduleTask("reminder", 60000); // 1 minute in the future
+  
+  // Fast-forward time by 1 minute
+  await vi.advanceTimersByTimeAsync(60000);
+  
+  // Verify the scheduled task executed
+  expect(await scheduler.getCompletedTasks()).toContain("reminder");
+});
+```
+
+```ts src/index.ts
+import { actor, setup } from "actor-core";
+
+const scheduler = actor({
+  state: { 
+    tasks: [],
+    completedTasks: []
+  },
+  actions: {
+    scheduleTask: (c, taskName: string, delayMs: number) => {
+      c.state.tasks.push(taskName);
+      // Schedule "completeTask" to run after the specified delay
+      c.schedule.after(delayMs, "completeTask", taskName);
+      return { success: true };
+    },
+    completeTask: (c, taskName: string) => {
+      // This action will be called by the scheduler when the time comes
+      c.state.completedTasks.push(taskName);
+      return { completed: taskName };
+    },
+    getCompletedTasks: (c) => {
+      return c.state.completedTasks;
+    }
+  }
+});
+
+export const app = setup({
+  actors: { scheduler }
+});
+
+export type App = typeof app;
+```
+</CodeGroup>
+
+The `setupTest` function automatically calls `vi.useFakeTimers()`, allowing you to control time in your tests with functions like `vi.advanceTimersByTimeAsync()`. This makes it possible to test scheduled operations without waiting for real time to pass.
+
+## Best Practices
+
+1. **Isolate tests**: Each test should run independently, avoiding shared state.
+2. **Test edge cases**: Verify how your actor handles invalid inputs, concurrent operations, and error conditions.
+3. **Mock time**: Use Vitest's timer mocks for testing scheduled operations.
+4. **Use realistic data**: Test with data that resembles production scenarios.
+
+ActorCore's testing framework automatically handles server setup and teardown, so you can focus on writing effective tests for your business logic.

docs/docs.json

@@ -69,8 +69,9 @@
                 "pages": [
                   "concepts/connections",
                   "concepts/metadata",
-                  "concepts/cors",
+                  "concepts/testing",
                   "concepts/logging",
+                  "concepts/cors",
                   "concepts/scaling",
                   "concepts/external-sql",
                   {