Ian/component test docs (#43745)

- Add sections for testing components

GitOrigin-RevId: ec2e2658f52cad62bdcfbdbc11b8fb1f779109c6

Author: ianmacartney

npm-packages/docs/docs/components/authoring.mdx

@@ -589,3 +589,86 @@ export const count = query({
 
 This explicit passing makes it clear what data flows between the app and
 component, making your component easier to understand and test.
+
+## Testing
+
+### Testing implementations
+
+To test components, you can use the
+[`convex-test` library](/testing/convex-test.mdx). The main difference is that
+you must provide the schema and modules to the test instance.
+
+```ts title="component/some.test.ts"
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+import schema from "./schema.ts";
+const modules = import.meta.glob("./**/*.ts");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+
+test("Test something with a local component", async () => {
+  const t = initConvexTest();
+  // Test like you would normally.
+  await t.run(async (ctx) => {
+    await ctx.db.insert("myComponentTable", { name: "test" });
+  });
+});
+```
+
+If your component has child components, see the
+[Testing components](/components/using.mdx#testing-components) section in the
+Using Components documentation.
+
+### Testing the API and client code
+
+To test the functions that are exported from the component to run in the app's
+environment, you can follow the same approach as in
+[Using Components](/components/using.mdx#testing-components) and test it from an
+app that uses the component.
+
+The template component includes an example app in part for this purpose: to
+exercise the component's bundled code as it will be used by apps installing it.
+
+### Exporting test helpers
+
+Most components export testing helpers to make it easy to register the component
+with the test instance. Here is an example from the
+[template component’s `/test` entrypoint](https://github.com/get-convex/templates/blob/main/template-component/src/test.ts):
+
+```ts
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "sampleComponent",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };
+```
+
+For NPM packages, this is exposed as `@your/package/test` in the package's
+`package.json`:
+
+```json
+{
+  ...
+  "exports": {
+    ...
+    "./test": "./src/test.ts",
+    ...
+  }
+}
+```

npm-packages/docs/docs/components/using.mdx

@@ -153,6 +153,69 @@ from certain components.
   />
 </p>
 
+## Testing components
+
+When writing tests with [`convex-test`](/testing/convex-test.mdx), that use
+components, you must register the component with the test instance. This tells
+it what schema to validate and where to find the component source code. Most
+components export convenient helper functions on `/test` to make this easy:
+
+```ts title="convex/some.test.ts"
+import agentTest from "@convex-dev/agent/test";
+import { expect, test } from "vitest";
+import { convexTest } from "convex-test";
+import { components } from "./_generated/api";
+import { createThread } from "@convex-dev/agent";
+
+// Define this once, often in a shared test helper file.
+export function initConvexTest() {
+  const t = convexTest();
+  // highlight-next-line
+  agentTest.register(t);
+  return t;
+}
+
+test("Agent createThread", async () => {
+  const t = initConvexTest();
+
+  const threadId = await t.run(async (ctx) => {
+    // Calling functions that use ctx and components.agent
+    return await createThread(ctx, components.agent, {
+      title: "Hello, world!",
+    });
+  });
+  // Calling functions directly on the component's API
+  const thread = await t.query(components.agent.threads.getThread, {
+    threadId,
+  });
+  expect(thread).toMatchObject({
+    title: "Hello, world!",
+  });
+});
+```
+
+If you need to register the component yourself, you can do so by passing the
+component's schema and modules to the test instance.
+
+```ts title="convex/manual.test.ts"
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+import schema from "./path/to/component/schema.ts";
+const modules = import.meta.glob("./path/to/component/**/*.ts");
+
+test("Test something with a local component", async () => {
+  const t = convexTest();
+  t.registerComponent("componentName", schema, modules);
+
+  await t.run(async (ctx) => {
+    await ctx.runQuery(components.componentName.someQuery, {
+      arg: "value",
+    });
+  });
+});
+```
+
 ## Log Streams
 
 You can use the `data.function.component_path` field in