@crab-dev/wake 0.1.21 → 0.1.22

package/index.cjs

@@ -2,6 +2,10 @@
 
 const { EventEmitter } = require('node:events')
 const { loadNative } = require('./loader.cjs')
+const {
+  registerTestContext,
+  setTestContextFatalError,
+} = require('./test-context-internal.cjs')
 const {
   WakeError,
   fromNativeError,
@@ -25,6 +29,196 @@ async function bundle(options) {
   return invoke(native.bundle(JSON.stringify(value), signal))
 }
 
+function splitTestOptions(options) {
+  try {
+    return splitOptions(options)
+  } catch (error) {
+    if (error instanceof WakeError && error.code === 'WAKE_CONFIG') {
+      throw new WakeError('WAKE_TEST_CONFIG', error.message, { cause: error })
+    }
+    throw error
+  }
+}
+
+async function runTests(options) {
+  const [value, signal] = splitTestOptions(options)
+  return invoke(native.runTests(
+    JSON.stringify(value),
+    signal,
+    native.__wakeTestHostPath,
+  ))
+}
+
+class TestContext extends EventEmitter {
+  #native
+  #closed = false
+  #eventPoll
+
+  constructor(handle) {
+    super()
+    this.#native = handle
+    registerTestContext(this, handle)
+  }
+
+  get closed() {
+    return this.#closed || this.#native.closed
+  }
+
+  get watching() {
+    return Boolean(this.#native.watching)
+  }
+
+  async run() {
+    if (this.closed) throw new WakeError('WAKE_TEST_CONTEXT', 'TestContext has already been closed')
+    try {
+      const result = await invoke(this.#native.run())
+      this.#flushEvents()
+      return result
+    } catch (error) {
+      this.#flushEvents()
+      throw error
+    }
+  }
+
+  startWatch() {
+    if (this.closed) throw new WakeError('WAKE_TEST_CONTEXT', 'TestContext has already been closed')
+    try {
+      this.#native.startWatch()
+      this.#flushEvents()
+      this.#startEventPoll()
+      return this
+    } catch (error) {
+      throw fromNativeError(error)
+    }
+  }
+
+  stopWatch() {
+    if (this.closed) return this
+    try {
+      this.#native.stopWatch()
+      this.#flushEvents()
+      this.#stopEventPoll()
+      return this
+    } catch (error) {
+      throw fromNativeError(error)
+    }
+  }
+
+  async close() {
+    if (this.#closed) return
+    this.#closed = true
+    this.#stopEventPoll()
+    try {
+      await invoke(this.#native.close())
+    } finally {
+      this.#flushEvents()
+    }
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.close()
+  }
+
+  #flushEvents() {
+    this.#dispatchEvents(this.#readEvents())
+  }
+
+  #readEvents() {
+    let events
+    try {
+      events = JSON.parse(this.#native.eventsJson())
+    } catch (cause) {
+      const detail = cause instanceof Error ? cause.message : String(cause)
+      throw new WakeError(
+        'WAKE_TEST_HOST',
+        `Wake returned an invalid test event stream: ${detail}`,
+        { cause },
+      )
+    }
+    if (!Array.isArray(events)) {
+      throw new WakeError('WAKE_TEST_HOST', 'Wake returned a non-array test event stream')
+    }
+    return events
+  }
+
+  #dispatchEvents(events) {
+    for (const event of events) {
+      switch (event.type) {
+        case 'runStart':
+          this.emit('runStart', { runId: event.runId, watching: event.watching })
+          break
+        case 'testCaseResult':
+          this.emit('testCaseResult', {
+            runId: event.runId,
+            suiteId: event.suiteId,
+            result: event.result,
+          })
+          break
+        case 'suiteResult':
+          this.emit('suiteResult', {
+            runId: event.runId,
+            result: event.result,
+          })
+          break
+        case 'diagnostic':
+          this.emit('diagnostic', event.diagnostic)
+          break
+        case 'runComplete':
+          this.emit('runComplete', event.result)
+          break
+        case 'closed':
+          this.emit('closed')
+          break
+        default:
+          throw new WakeError('WAKE_TEST_HOST', `Unknown test-host event: ${String(event.type)}`)
+      }
+    }
+  }
+
+  #startEventPoll() {
+    if (this.#eventPoll) return
+    this.#eventPoll = setInterval(() => {
+      let events
+      try {
+        events = this.#readEvents()
+      } catch (error) {
+        this.#stopEventPoll()
+        const fatalError = error instanceof WakeError
+          ? error
+          : new WakeError('WAKE_TEST_HOST', error instanceof Error ? error.message : String(error), {
+              cause: error,
+            })
+        setTestContextFatalError(this, fatalError)
+        // Host terminals are drained as ordered native events before this error becomes visible;
+        // closing then supplies the final public `closed` event without fabricating a duplicate
+        // JavaScript diagnostic.
+        void this.close().catch(() => {})
+        return
+      }
+      // User listeners execute outside the native/protocol error boundary. Their exceptions are
+      // ordinary EventEmitter failures and must never be relabeled as WAKE_TEST_HOST.
+      this.#dispatchEvents(events)
+    }, 25)
+  }
+
+  #stopEventPoll() {
+    if (!this.#eventPoll) return
+    clearInterval(this.#eventPoll)
+    this.#eventPoll = undefined
+  }
+}
+
+async function createTestContext(options) {
+  const [value] = splitTestOptions(options)
+  try {
+    return new TestContext(
+      native.createTestContext(JSON.stringify(value), native.__wakeTestHostPath),
+    )
+  } catch (error) {
+    throw fromNativeError(error)
+  }
+}
+
 async function buildLibrary(options) {
   const [value, signal] = splitOptions(options)
   return invoke(native.buildLibrary(JSON.stringify(value), signal))
@@ -208,14 +402,17 @@ function startDocsDevServer(options) {
 module.exports = {
   BuildContext,
   DevServer,
+  TestContext,
   WakeError,
   build,
   buildLibrary,
   buildDocs,
   bundle,
+  runTests,
   generateCssToken,
   generateDocgen,
   createBuildContext,
+  createTestContext,
   startDevServer,
   startDocsDevServer,
   version,

package/index.d.ts

@@ -20,6 +20,23 @@ export type WakeErrorCode =
   | 'WAKE_LIBRARY_BUILD'
   | 'WAKE_LIBRARY_TYPE'
   | 'WAKE_LIBRARY_OUTPUT'
+  | 'WAKE_TEST_CONFIG'
+  | 'WAKE_TEST_DISCOVERY'
+  | 'WAKE_TEST_RUNTIME'
+  | 'WAKE_TEST_TIMEOUT'
+  | 'WAKE_TEST_SNAPSHOT'
+  | 'WAKE_TEST_COVERAGE'
+  | 'WAKE_TEST_HOST'
+  | 'WAKE_TEST_UNSUPPORTED'
+  | 'WAKE_TEST_CONTEXT'
+  | 'WAKE_TEST_DOM'
+  | 'WAKE_TEST_BROWSER'
+  | 'WAKE_TEST_REACT_VERSION'
+  | 'WAKE_TEST_NETWORK'
+  | 'WAKE_TEST_LEAK'
+  | 'WAKE_TEST_BUSY'
+  | 'WAKE_TEST_UNKNOWN_RUN'
+  | 'WAKE_TEST_UNKNOWN_WATCH'
 
 export interface DiagnosticLocation {
   /** One-based source line. */
@@ -66,6 +83,238 @@ export interface BuildOptions extends ProjectOptions {
   sourceMap?: boolean
 }
 
+export type TestEnvironment = 'auto' | 'dom' | 'browser'
+export type TestReporter = 'pretty' | 'json' | 'junit'
+export type SnapshotUpdateMode = 'none' | 'new' | 'all'
+export type TestWorkers = number | 'auto' | `${number}%`
+
+export interface TestOptions {
+  root?: string
+  patterns?: string[]
+  namePattern?: string
+  projects?: string[]
+  environment?: TestEnvironment
+  watch?: boolean
+  changed?: boolean
+  related?: string[]
+  coverage?: boolean
+  updateSnapshots?: SnapshotUpdateMode
+  serial?: boolean
+  workers?: TestWorkers
+  bail?: number
+  shard?: `${number}/${number}`
+  seed?: string
+  shuffle?: boolean
+  reporter?: TestReporter
+  output?: string
+  allowNoTests?: boolean
+  browserPath?: string
+  headful?: boolean
+}
+
+export type TestCaseStatus = 'passed' | 'failed' | 'skipped' | 'todo'
+export type TestSuiteStatus = 'passed' | 'failed' | 'skipped'
+export type TestTerminationReason =
+  | 'completed'
+  | 'cancelled'
+  | 'bail'
+  | 'watch-restart'
+  | 'host-crash'
+  | 'timeout'
+  | 'oom'
+  | 'internal-error'
+
+export interface TestLocation {
+  path: string
+  line: number
+  column: number
+  endLine: number | null
+  endColumn: number | null
+}
+
+export interface TestDiff {
+  expected: string | null
+  received: string | null
+  unified: string | null
+}
+
+export interface TestFailure {
+  message: string
+  code: string | null
+  stack: string | null
+  location: TestLocation | null
+  diff: TestDiff | null
+}
+
+export interface TestCaseResult {
+  id: string
+  name: string
+  fullName: string
+  status: TestCaseStatus
+  durationMs: number
+  assertions: number
+  attempts: number
+  location: TestLocation | null
+  failures: TestFailure[]
+}
+
+export interface SnapshotSummary {
+  added: number
+  matched: number
+  unmatched: number
+  updated: number
+  obsolete: number
+  filesRemoved: number
+}
+
+export interface CoverageMetric {
+  covered: number
+  total: number
+  percent: number
+}
+
+export interface CoverageMetrics {
+  lines: CoverageMetric
+  functions: CoverageMetric
+  blocks: CoverageMetric
+}
+
+export interface CoverageFile extends CoverageMetrics {
+  path: string
+}
+
+export interface CoverageResult {
+  summary: CoverageMetrics
+  files: CoverageFile[]
+  reportArtifactIds: string[]
+}
+
+export interface BrowserEnvironmentInfo {
+  name: string
+  version: string
+  headless: boolean
+}
+
+export interface TestEnvironmentInfo {
+  kind: 'dom' | 'browser'
+  react: string | null
+  reactDom: string | null
+  v8: string
+  browser: BrowserEnvironmentInfo | null
+}
+
+export type TestMetadataValue =
+  | null
+  | boolean
+  | number
+  | string
+  | TestMetadataValue[]
+  | { [key: string]: TestMetadataValue }
+
+export interface TestArtifact {
+  id: string
+  kind: string
+  path: string
+  suiteId: string | null
+  testId: string | null
+  metadata: Record<string, TestMetadataValue>
+}
+
+export interface TestDiagnostic {
+  severity: 'error' | 'warning' | 'note' | 'help'
+  code: string
+  message: string
+  path: string | null
+  location: TestLocation | null
+  notes?: string[]
+}
+
+export interface TestLeak {
+  kind: 'timer' | 'listener' | 'task' | 'socket' | 'network' | 'other'
+  description: string
+  location: TestLocation | null
+  stack: string | null
+}
+
+export interface TestSuiteResult {
+  id: string
+  path: string
+  name: string | null
+  project: string | null
+  environment: TestEnvironmentInfo | null
+  status: TestSuiteStatus
+  durationMs: number
+  tests: TestCaseResult[]
+  failures: TestFailure[]
+  snapshot: SnapshotSummary | null
+}
+
+export interface TestStatusCounts {
+  total: number
+  passed: number
+  failed: number
+  skipped: number
+}
+
+export interface TestCaseStatusCounts extends TestStatusCounts {
+  todo: number
+}
+
+export interface TestRunCounts {
+  suites: TestStatusCounts
+  tests: TestCaseStatusCounts
+}
+
+export interface TestRunResult {
+  schemaVersion: 'wake.test.v1'
+  runId: string
+  success: boolean
+  seed: string
+  durationMs: number
+  terminationReason: TestTerminationReason
+  environment: TestEnvironmentInfo
+  suites: TestSuiteResult[]
+  counts: TestRunCounts
+  snapshot: SnapshotSummary
+  coverage: CoverageResult | null
+  leaks: TestLeak[]
+  artifacts: TestArtifact[]
+  diagnostics: TestDiagnostic[]
+}
+
+export interface TestRunStartEvent {
+  runId: string
+  watching: boolean
+}
+
+export interface TestCaseResultEvent {
+  runId: string
+  suiteId: string
+  result: TestCaseResult
+}
+
+export interface TestSuiteResultEvent {
+  runId: string
+  result: TestSuiteResult
+}
+
+export class TestContext extends EventEmitter {
+  private constructor()
+  readonly watching: boolean
+  readonly closed: boolean
+  run(): Promise<TestRunResult>
+  startWatch(): this
+  stopWatch(): this
+  close(): Promise<void>
+  [Symbol.asyncDispose](): Promise<void>
+  on(event: 'runStart', listener: (event: TestRunStartEvent) => void): this
+  on(event: 'testCaseResult', listener: (event: TestCaseResultEvent) => void): this
+  on(event: 'suiteResult', listener: (event: TestSuiteResultEvent) => void): this
+  on(event: 'runComplete', listener: (result: TestRunResult) => void): this
+  on(event: 'diagnostic', listener: (diagnostic: TestDiagnostic) => void): this
+  on(event: 'closed', listener: () => void): this
+}
+
 export type BundlePlatform = 'browser' | 'node'
 export type BundleFormat = 'iife' | 'cjs'
 export type NodeTarget = `node${number}` | `node${number}.${number}`
@@ -272,6 +521,8 @@ export function buildLibrary(options?: LibraryBuildOptions): Promise<LibraryBuil
 export function generateCssToken(options?: GenerateCssTokenOptions): Promise<GenerateCssTokenResult>
 export function generateDocgen(options?: GenerateDocgenOptions): Promise<GenerateDocgenResult>
 export function createBuildContext(options?: BuildOptions): Promise<BuildContext>
+export function runTests(options?: TestOptions & { signal?: AbortSignal }): Promise<TestRunResult>
+export function createTestContext(options?: TestOptions): Promise<TestContext>
 export function startDevServer(options?: DevServerOptions): Promise<DevServer>
 export function buildDocs(options?: DocsBuildOptions): Promise<DocsBuildResult>
 export function startDocsDevServer(options?: DocsDevServerOptions): Promise<DevServer>
@@ -279,6 +530,7 @@ export function startDocsDevServer(options?: DocsDevServerOptions): Promise<DevS
 declare const wake: {
   BuildContext: typeof BuildContext
   DevServer: typeof DevServer
+  TestContext: typeof TestContext
   WakeError: typeof WakeError
   build: typeof build
   buildLibrary: typeof buildLibrary
@@ -287,6 +539,8 @@ declare const wake: {
   generateCssToken: typeof generateCssToken
   generateDocgen: typeof generateDocgen
   createBuildContext: typeof createBuildContext
+  runTests: typeof runTests
+  createTestContext: typeof createTestContext
   startDevServer: typeof startDevServer
   startDocsDevServer: typeof startDocsDevServer
   version: typeof version

package/index.mjs

@@ -3,14 +3,17 @@ import api from './index.cjs'
 export const {
   BuildContext,
   DevServer,
+  TestContext,
   WakeError,
   build,
   buildLibrary,
   buildDocs,
   bundle,
+  runTests,
   generateCssToken,
   generateDocgen,
   createBuildContext,
+  createTestContext,
   startDevServer,
   startDocsDevServer,
   version,

package/loader.cjs

@@ -17,9 +17,25 @@ function unsupported(message, cause) {
   return error
 }
 
+function attachTestHost(native, nativePath) {
+  const hostPath = process.env.WAKE_TEST_HOST_PATH || path.join(
+    path.dirname(nativePath),
+    'test-host',
+    process.platform === 'win32' ? 'wake-test-host.exe' : 'wake-test-host',
+  )
+  Object.defineProperty(native, '__wakeTestHostPath', {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: hostPath,
+  })
+  return native
+}
+
 function loadNative() {
   if (process.env.WAKE_NATIVE_PATH) {
-    return require(path.resolve(process.env.WAKE_NATIVE_PATH))
+    const nativePath = path.resolve(process.env.WAKE_NATIVE_PATH)
+    return attachTestHost(require(nativePath), nativePath)
   }
 
   const key = `${process.platform}-${process.arch}`
@@ -41,7 +57,8 @@ function loadNative() {
   }
 
   try {
-    return require(packageName)
+    const nativePath = require.resolve(packageName)
+    return attachTestHost(require(nativePath), nativePath)
   } catch (cause) {
     throw unsupported(
       `Unable to load ${packageName} for ${process.platform}/${process.arch}. ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crab-dev/wake",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Wake native web build tools for Node.js",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -22,6 +22,16 @@
       "import": "./experimental.mjs",
       "require": "./experimental.cjs"
     },
+    "./test": {
+      "types": "./test.d.ts",
+      "import": "./test.mjs",
+      "require": "./test.cjs"
+    },
+    "./test/react": {
+      "types": "./test-react.d.ts",
+      "import": "./test-react.mjs",
+      "require": "./test-react.cjs"
+    },
     "./internal/components-runtime": {
       "types": "./internal/components-runtime.d.ts",
       "import": "./internal/components-runtime.mjs"
@@ -41,6 +51,12 @@
     "*.mjs",
     "index.d.ts",
     "experimental.d.ts",
+    "test.cjs",
+    "test.mjs",
+    "test.d.ts",
+    "test-react.cjs",
+    "test-react.mjs",
+    "test-react.d.ts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE-MIT",
@@ -50,7 +66,7 @@
     "node": ">=22.14 <27"
   },
   "dependencies": {
-    "@crab-dev/css": "0.1.21",
+    "@crab-dev/css": "0.1.22",
     "@crab-dev/rc-alert": "^0.0.2",
     "@crab-dev/rc-button": "^0.0.2",
     "@crab-dev/rc-dialog": "^0.0.2",
@@ -71,15 +87,15 @@
     "string-width": "8.2.2"
   },
   "peerDependencies": {
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8"
+    "react": ">=19.2.8 <19.3.0",
+    "react-dom": ">=19.2.8 <19.3.0"
   },
   "optionalDependencies": {
-    "@crab-dev/wake-darwin-arm64": "0.1.21",
-    "@crab-dev/wake-darwin-x64": "0.1.21",
-    "@crab-dev/wake-linux-arm64-gnu": "0.1.21",
-    "@crab-dev/wake-linux-x64-gnu": "0.1.21",
-    "@crab-dev/wake-win32-x64-msvc": "0.1.21"
+    "@crab-dev/wake-darwin-arm64": "0.1.22",
+    "@crab-dev/wake-darwin-x64": "0.1.22",
+    "@crab-dev/wake-linux-arm64-gnu": "0.1.22",
+    "@crab-dev/wake-linux-x64-gnu": "0.1.22",
+    "@crab-dev/wake-win32-x64-msvc": "0.1.22"
   },
   "publishConfig": {
     "access": "public",

package/test-context-internal.cjs

@@ -0,0 +1,30 @@
+'use strict'
+
+const contexts = new WeakMap()
+
+function registerTestContext(context, handle) {
+  contexts.set(context, { handle, fatalError: undefined })
+}
+
+function sendTestWatchControl(context, control) {
+  const record = contexts.get(context)
+  if (!record) throw new TypeError('Expected a Wake TestContext')
+  record.handle.watchControl(JSON.stringify(control))
+}
+
+function setTestContextFatalError(context, error) {
+  const record = contexts.get(context)
+  if (!record) throw new TypeError('Expected a Wake TestContext')
+  record.fatalError = error
+}
+
+function getTestContextFatalError(context) {
+  return contexts.get(context)?.fatalError
+}
+
+module.exports = {
+  getTestContextFatalError,
+  registerTestContext,
+  sendTestWatchControl,
+  setTestContextFatalError,
+}