AGENTS.md

1# Shared Test Helper Boundary
2 
3This directory holds shared test helpers reused by core and bundled plugin
4tests.
5 
6## Bundled Plugin Imports
7 
8- Shared helpers in this tree must not hardcode repo-relative imports into
9  `extensions/**`.
10- When a helper needs a bundled plugin public surface, go through
11  `src/test-utils/bundled-plugin-public-surface.ts`.
12- Prefer `loadBundledPluginApiSync(...)`,
13  `loadBundledPluginRuntimeApiSync(...)`,
14  `loadBundledPluginContractApiSync(...)`, and
15  `loadBundledPluginTestApiSync(...)` for eager access to exported surfaces.
16- Prefer `resolveRelativeBundledPluginPublicModuleId(...)` or
17  `resolveBundledPluginPublicModulePath(...)` when a helper needs a module id
18  or filesystem path for dynamic import, mocking, or loading a plugin entrypoint
19  such as `index.js`.
20- If `vi.hoisted(...)` is involved, do not call imported helper functions from
21  inside the hoisted callback. Resolve the module id outside the callback or
22  switch to `vi.doMock(...)`.
23- Do not keep plugin-local deep mocks or private `src/**` knowledge in shared
24  helpers. Move those helpers into the owning bundled plugin package instead.
25 
26## Intent
27 
28- Keep shared helpers aligned with the same public/plugin boundary that
29  production code uses.
30- Avoid shared helper debt that makes core test lanes depend on bundled plugin
31  private layout.
32