@namzu/sandbox 18.1.1 → 19.0.0

package/src/testing/sandbox-conformance.ts

@@ -71,12 +71,29 @@ import type {
 	TerminalSession,
 } from '@namzu/sdk'
 
-import type {
-	ConformanceAssertion,
-	ConformanceDescribe,
-	ConformanceExpect,
-	ConformanceIt,
-} from '@namzu/sdk/testing'
+import { ensureSandboxSeed } from '../seed/index.js'
+
+/**
+ * The runner shapes the suite takes, declared here rather than imported.
+ * `@namzu/sdk/testing` exported them beside the checkpoint-store suite, and
+ * that suite and these exports went with it; they are structurally the
+ * same types, so a runner written against either still fits.
+ */
+
+/** The assertions the suite uses, and nothing more. */
+interface ConformanceAssertion {
+	toBe(expected: unknown): void
+	toEqual(expected: unknown): void
+	toBeGreaterThan(expected: number): void
+	toMatch(expected: RegExp): void
+}
+
+/** Shape of the `expect` a runner supplies. */
+type ConformanceExpect = (actual: unknown) => ConformanceAssertion
+/** Shape of the `it` a runner supplies. */
+type ConformanceIt = (name: string, body: () => Promise<void>) => unknown
+/** Shape of the `describe` a runner supplies. */
+type ConformanceDescribe = (name: string, body: () => void) => unknown
 
 /**
  * The contract revision these assertions express. Carried on the describe
@@ -172,6 +189,14 @@ export interface SandboxConformanceOptions {
 	 * capability.
 	 */
 	readonly supportsRangedAndStreamedReads?: boolean
+	/**
+	 * A git repository the guest can clone, and an absolute directory to
+	 * clone it under, for the `ensureSandboxSeed` case. Absent (the default),
+	 * the case is a named skip: this suite cannot assume a guest has git or a
+	 * route to any repository. The URL follows the seed's own rules (`https://`,
+	 * or `http://` for a proxy-brokered host, no credentials).
+	 */
+	readonly seed?: { readonly url: string; readonly root: string }
 }
 
 /** Assert `call()` rejects. The contract cares that admission was refused, never the message. */
@@ -1194,6 +1219,27 @@ export function defineSandboxConformance(options: SandboxConformanceOptions): vo
 			)
 		})
 	})
+
+	describe(`${label} seed`, () => {
+		const seedOption = options.seed
+		const title = 'prepares a seed once, and a second call finds it present at the same commit'
+		it(
+			seedOption === undefined ? `${title} (skipped: no seed repository was given)` : title,
+			seedOption === undefined
+				? async () => {}
+				: withSandbox(async (sandbox) => {
+						const seed = {
+							name: 'conformance',
+							repositories: [{ name: 'repo', url: seedOption.url }],
+						}
+						const first = await ensureSandboxSeed(sandbox, seed, { root: seedOption.root })
+						expect(first.repositories[0]?.status).toBe('cloned')
+						const second = await ensureSandboxSeed(sandbox, seed, { root: seedOption.root })
+						expect(second.repositories[0]?.status).toBe('present')
+						expect(second.repositories[0]?.commit).toBe(first.repositories[0]?.commit)
+					}),
+		)
+	})
 }
 
 // Re-exported so a caller building a recording harness (as this suite's own