@alloy-js/core 0.23.0-dev.12 → 0.23.0-dev.15

package/testing/create-test-wrapper.tsx

@@ -2,20 +2,94 @@ import {
   Children,
   Declaration,
   For,
+  NameConflictResolver,
   Namekey,
   namekey,
+  NamePolicy,
   Output,
   OutputSymbol,
   shallowReactive,
 } from "../src/index.js";
 
+/**
+ * Test harness returned by {@link createTestWrapper}.
+ */
 export interface TestWrapper {
+  /**
+   * JSX wrapper providing Output + a file-level component + language scope context.
+   * Name policy is applied only when `namePolicy`/`nameConflictResolver` are
+   * passed to {@link createTestWrapper}. Pre-declares all namekeys created by
+   * {@link TestWrapper.defkey} before rendering children.
+   */
   Wrapper: (props: { children: Children }) => Children;
+
+  /**
+   * Creates a stable `Namekey` and schedules a pre-declaration inside
+   * {@link TestWrapper.Wrapper}.
+   *
+   * @remarks
+   * Call `defkey(name)` before rendering. `Wrapper` renders
+   * `<Declaration symbol={...} />` for this name so `<Reference>` to the
+   * returned namekey resolves without requiring an explicit `<Declaration>`
+   * in the test body.
+   *
+   * @example
+   * ```tsx
+   * const { Wrapper, defkey } = createTestWrapper(...);
+   * const fooKey = defkey("foo");
+   * expect(
+   *   <Wrapper><MyComponent refkey={fooKey} /></Wrapper>
+   * ).toRenderTo(`foo`);
+   * ```
+   */
   defkey: (name: string) => Namekey;
 }
 
 /**
- * Generic test wrapper creator.
+ * Create a reusable test harness for a language package. Returns a `Wrapper`
+ * component (wraps content in `<Output>` + `<SourceFile>`) and a `defkey`
+ * helper that creates stable namekeys for pre-declaring symbols.
+ *
+ * @remarks
+ *
+ * Downstream consumers import and call this from the language package's
+ * `testing/` entrypoint. The `Wrapper` automatically declares symbols
+ * created by `defkey` before rendering children, so tests can reference
+ * symbols without explicit `<Declaration>` boilerplate.
+ *
+ * @example
+ * ```ts
+ * // In your language package's testing/ entrypoint:
+ * import { FileComponent } from "./components/index.js"; // your language package's top-level file component
+ * import { createTestWrapper, type TestWrapper } from "@alloy-js/core/testing";
+ *
+ * export function createMyLangTestWrapper(): TestWrapper {
+ *   return createTestWrapper({
+ *     filePath: "test.ext",
+ *     useScope: useMyLangScope,
+ *     makeSymbol: (nk, scope) => new MyOutputSymbol(nk, scope),
+ *     SourceFile: FileComponent,
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Extend your language test factory to accept and forward namePolicy:
+ * export function createMyLangTestWrapper(namePolicy?: NamePolicy<string>): TestWrapper {
+ *   return createTestWrapper({ ...langOpts, namePolicy });
+ * }
+ *
+ * // In a name-policy test:
+ * const { Wrapper } = createMyLangTestWrapper(myNamePolicy);
+ * const fooKey = namekey("foo"); // namekey(), not defkey — name policy applies
+ * // namekey() schedules no pre-declaration; the test body must declare the symbol.
+ * expect(
+ *   <Wrapper>
+ *     <MyDeclaration refkey={fooKey} name="foo" />
+ *   </Wrapper>
+ * ).toRenderTo("FOO");
+ * ```
  */
 export function createTestWrapper<
   SymbolT extends OutputSymbol,
@@ -25,6 +99,8 @@ export function createTestWrapper<
   useScope: () => ScopeT | undefined;
   makeSymbol: (nk: Namekey, scope: ScopeT) => SymbolT;
   SourceFile: (props: { path: string; children: Children }) => any;
+  namePolicy?: NamePolicy<string>;
+  nameConflictResolver?: NameConflictResolver;
 }): TestWrapper {
   const seen = shallowReactive(new Map<string, Namekey>());
   const created = new Map<Namekey, SymbolT>();
@@ -55,7 +131,10 @@ export function createTestWrapper<
   function Wrapper(props: { children: Children }) {
     const SF = opts.SourceFile;
     return (
-      <Output>
+      <Output
+        namePolicy={opts.namePolicy}
+        nameConflictResolver={opts.nameConflictResolver}
+      >
         <SF path={opts.filePath}>
           <For each={[...seen.values()]} joiner="">
             {(nk) => <Declaration symbol={createSymbol(nk)} />}

package/testing/extend-expect.ts

@@ -12,9 +12,30 @@ import { expect } from "vitest";
 import { flushJobs, flushJobsAsync } from "../src/scheduler.js";
 import { dedent } from "./render.js";
 
-interface ToRenderToOptions {
+/**
+ * Print options passed to `toRenderTo` / `toRenderToAsync`. These override
+ * the per-`SourceFile` print settings for the duration of the assertion,
+ * which is useful when forcing line-breaking with a narrow `printWidth` in
+ * tests without needing extremely long inputs.
+ *
+ * @example
+ * ```ts
+ * expect(<MyList items={["a", "b", "c"]} />).toRenderTo(
+ *   `
+ *   a,
+ *   b,
+ *   c
+ *   `,
+ *   { printWidth: 10 }
+ * );
+ * ```
+ */
+export interface ToRenderToOptions {
+  /** Maximum line width before the formatter wraps output. */
   printWidth?: number;
+  /** Number of spaces per indentation level. */
   tabWidth?: number;
+  /** Use tab characters instead of spaces. */
   useTabs?: boolean;
 }
 

package/testing/index.ts

@@ -1,3 +1,3 @@
-import "./extend-expect.js";
 export * from "./create-test-wrapper.jsx";
+export * from "./extend-expect.js";
 export * from "./render.js";

package/testing/render.ts

@@ -2,10 +2,19 @@ import { Children, printTree, renderTree } from "../src/index.js";
 
 export { printTree } from "../src/index.js";
 
+/**
+ * Render a JSX element tree to a string. Convenience wrapper combining
+ * `renderTree` and `printTree`.
+ */
 export function renderToString(element: Children) {
   return printTree(renderTree(element));
 }
 
+/**
+ * Dedented template literal tag. Strips leading/trailing blank lines and
+ * removes the common leading whitespace from all lines — useful for
+ * multi-line expected output in tests.
+ */
 export function d(strings: TemplateStringsArray, ...values: any[]): string {
   // Combine the strings and values
   const result = strings.reduce(

package/testing/vitest.d.ts

@@ -1,10 +1,5 @@
 import "vitest";
-
-interface ToRenderToRenderOptions {
-  printWidth?: number;
-  tabWidth?: number;
-  useTabs?: boolean;
-}
+import type { ToRenderToOptions } from "./extend-expect.js";
 
 interface ExpectedDiagnostic {
   message: string | RegExp;
@@ -14,11 +9,11 @@ interface ExpectedDiagnostic {
 interface CustomMatchers<R = unknown> {
   toRenderTo: (
     str: string | Record<string, string>,
-    options?: ToRenderToRenderOptions,
+    options?: ToRenderToOptions,
   ) => R;
   toRenderToAsync: (
     str: string | Record<string, string>,
-    options?: ToRenderToRenderOptions,
+    options?: ToRenderToOptions,
   ) => Promise<R>;
   toHaveDiagnostics: (expectedDiagnostics: ExpectedDiagnostic[]) => R;
   toHaveDiagnosticsAsync: (