Files
orca/src/cli/plugin-authoring/plugin-test-runner.ts
Neil 531658f1d1 Plugin test kit: orca/testing, orca plugin test and orca plugin check (#36969)
* feat(plugins): orca/testing kit, `orca plugin test` and `orca plugin check`

- `orca/testing` mounts a components panel in plain Node (node:test, vitest, bun) with the real
  runtime and Orca's own tree validator: find by text/role/label/testId, press/type/submit/toggle/
  select that resolve once the panel settles, tree() snapshots, errors (with stacks) and warnings,
  persisted state (with stored() for migrations), emit/setVisible/rerender, and unmount running
  setup cleanup. It re-exports node:test and strict assert so tests type-check without @types/node.
- mockHost refuses what Orca refuses with the same codes (surface, capability from the manifest,
  params, a gesture method without a press), checks configured results against the host API, and
  records calls.
- `orca plugin test [dir]` discovers *.test.ts(x) and runs them with node:test through Node module
  hooks that resolve `orca` like the guest's import map and transpile/resolve sources exactly as
  Orca's build-less loader, or with the plugin's own vitest via a generated config.
- `orca plugin check [dir]` validates, then renders each components panel once and reports what it
  threw (file:line), layouts Orca would refuse, and props it would drop.
- The kit, hooks and register entry ship minified beside orca-runtime.mjs and are unpacked from asar;
  typings land in .orca/types/orca-testing. The components template and hello-tsx get sample tests.
- ui.error carries an optional stack; a new runtime starts every atom from its initial value; the
  hydration fallback timer is cleared once hydrated.

* plugins: run plugin test/check on a system Node or Orca's own, and warn they are unsandboxed

* test(plugins): run the shipped example plugin tests from the unit suite
2026-11-01 02:42:12 -08:00

135 lines
5.2 KiB
TypeScript

import { existsSync } from 'node:fs'
import { mkdir, readdir, writeFile } from 'node:fs/promises'
import { join, relative, sep } from 'node:path'
import { pathToFileURL } from 'node:url'
import { runProcess } from '@orca/process-host'
import { selectPluginTestNode, type PluginTestNode } from './plugin-test-node'
/** Plugin test files `orca plugin test` runs. */
export const PLUGIN_TEST_FILE = /\.test\.(?:tsx?|mts|jsx?|mjs)$/i
// Not plugin sources: dependencies, Orca's own generated files, VCS and build output.
const SKIPPED_DIRS = new Set(['node_modules', '.orca', '.git', 'dist', 'out', 'coverage'])
const defaultAppRoot = (): string => join(__dirname, '..', '..', '..')
/** The files Orca ships for testing components panels, from the app this CLI belongs to. */
export function pluginTestingFiles(appRoot = defaultAppRoot()) {
const dir = join(appRoot, 'resources', 'plugins', 'declarative')
return {
runtime: join(dir, 'orca-runtime.mjs'),
testing: join(dir, 'orca-testing.mjs'),
hooks: join(dir, 'orca-test-hooks.mjs'),
register: join(dir, 'orca-test-register.mjs')
}
}
/** Test files under `dir`, plugin-relative with `/`, sorted. */
export async function findPluginTestFiles(dir: string): Promise<string[]> {
const found: string[] = []
const walk = async (folder: string): Promise<void> => {
for (const entry of await readdir(folder, { withFileTypes: true })) {
if (entry.isDirectory()) {
if (!SKIPPED_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
await walk(join(folder, entry.name))
}
} else if (entry.isFile() && PLUGIN_TEST_FILE.test(entry.name)) {
found.push(relative(dir, join(folder, entry.name)).split(sep).join('/'))
}
}
}
await walk(dir)
return found.sort()
}
export type PluginTestRunner = 'node' | 'vitest'
/** The plugin's own vitest when it has one installed, else Node's built-in runner. */
export function pluginTestRunner(dir: string): { runner: PluginTestRunner; entry?: string } {
const vitest = join(dir, 'node_modules', 'vitest', 'vitest.mjs')
return existsSync(vitest) ? { runner: 'vitest', entry: vitest } : { runner: 'node' }
}
/** A Vite config that resolves `orca` like the guest's import map and transpiles like Orca. */
export function pluginVitestConfig(files: ReturnType<typeof pluginTestingFiles>): string {
const url = (path: string): string => JSON.stringify(pathToFileURL(path).href)
const path = (value: string): string => JSON.stringify(value)
return `// Written by \`orca plugin test\`. Do not edit.
import { transformPluginSourceForTest } from ${url(files.hooks)}
const SOURCE = /\\.(?:tsx?|mts|jsx)$/
export default {
esbuild: false,
plugins: [
{
name: 'orca-plugin-sources',
enforce: 'pre',
transform(code, id) {
const file = id.split('?')[0]
if (!SOURCE.test(file) || file.includes('/node_modules/')) return null
return { code: transformPluginSourceForTest(file, code), map: null }
}
}
],
resolve: {
alias: [
{ find: /^orca$/, replacement: ${path(files.runtime)} },
{ find: /^orca\\/jsx-(?:dev-)?runtime$/, replacement: ${path(files.runtime)} },
{ find: /^orca\\/testing$/, replacement: ${path(files.testing)} }
]
},
test: {
include: ['**/*.test.{ts,tsx,mts,js,jsx,mjs}'],
exclude: ['**/node_modules/**', '**/.orca/**'],
// One runtime instance for the panel and the kit: never let vite-node externalize them.
server: { deps: { inline: [/resources[\\\\/]plugins[\\\\/]declarative/] } }
}
}
`
}
/**
* Runs the plugin's tests and resolves with the runner's exit code. Output streams through; with
* `quietStdout` (the CLI's --json mode) the runner's stdout goes to stderr instead.
*/
export async function runPluginTests(options: {
dir: string
files: readonly string[]
appRoot?: string
quietStdout?: boolean
node?: PluginTestNode
}): Promise<{ runner: PluginTestRunner; code: number; node: PluginTestNode['source'] }> {
const testing = pluginTestingFiles(options.appRoot)
const selected = pluginTestRunner(options.dir)
const node = options.node ?? (await selectPluginTestNode())
const env = { ...process.env, ...node.env, ORCA_PLUGIN_TEST_ROOT: options.dir }
let args: string[]
if (selected.runner === 'vitest' && selected.entry) {
const configDir = join(options.dir, '.orca', 'test')
await mkdir(configDir, { recursive: true })
// `.orca/` is Orca's generated folder; it keeps itself out of Git.
if (!existsSync(join(options.dir, '.orca', '.gitignore'))) {
await writeFile(join(options.dir, '.orca', '.gitignore'), '*\n')
}
const config = join(configDir, 'vitest.config.mjs')
await writeFile(config, pluginVitestConfig(testing))
args = [selected.entry, 'run', '--config', config, '--root', options.dir, ...options.files]
} else {
args = [
'--enable-source-maps',
'--import',
pathToFileURL(testing.register).href,
'--test',
...options.files
]
}
const result = await runProcess({
program: node.program,
args,
cwd: options.dir,
env,
timeoutMs: null,
stdio: ['ignore', options.quietStdout ? 2 : 'inherit', 'inherit']
})
return { runner: selected.runner, code: result.code ?? 1, node: node.source }
}