@remix-run/test 0.0.0 → 0.1.0

package/src/lib/framework.ts

@@ -0,0 +1,251 @@
+import type { TestContext } from './context.ts'
+
+interface TestSuite {
+  name: string
+  tests: Test[]
+  only?: boolean
+  skip?: boolean
+  todo?: boolean
+  beforeEach?: () => void | Promise<void>
+  afterEach?: () => void | Promise<void>
+  beforeAll?: () => void | Promise<void>
+  afterAll?: () => void | Promise<void>
+}
+
+interface Test {
+  name: string
+  fn: (t?: any) => void | Promise<void>
+  suite: TestSuite
+  only?: boolean
+  skip?: boolean
+  todo?: boolean
+}
+
+// Holds lifecycle hooks registered at the top level (outside any describe).
+// Top-level describes inherit these hooks just like nested describes inherit
+// from their parent.
+const rootHooks: Pick<TestSuite, 'beforeEach' | 'afterEach' | 'beforeAll' | 'afterAll'> = {}
+
+let currentSuite: TestSuite | null = null
+const rootSuites: TestSuite[] = []
+
+// Lazily-created suite for top-level it() calls outside any describe().
+// Name '' causes the reporter to display these tests under "Global".
+// We check rootSuites.includes() so the suite is re-created after the executor
+// clears rootSuites between files (suites.length = 0) or after captureRegistration splices it.
+let implicitRootSuite: TestSuite | null = null
+function getImplicitRootSuite(): TestSuite {
+  if (!implicitRootSuite || !rootSuites.includes(implicitRootSuite)) {
+    implicitRootSuite = { name: '', tests: [], ...rootHooks }
+    rootSuites.push(implicitRootSuite)
+  }
+  return implicitRootSuite
+}
+
+// Expose for executor.ts which reads this global
+;(globalThis as any).__testSuites = rootSuites
+
+function registerDescribe(
+  name: string,
+  fn: () => void,
+  flags?: { only?: boolean; skip?: boolean },
+) {
+  // Nested describes are flattened: "Parent > Child"
+  let fullName = currentSuite ? `${currentSuite.name} > ${name}` : name
+  if (rootSuites.some((s) => s.name === fullName)) {
+    throw new Error(`Duplicate suite name: "${fullName}"`)
+  }
+  let suite: TestSuite = { name: fullName, tests: [], ...flags }
+
+  // Inherit lifecycle hooks from parent suite (or root hooks if at top level)
+  let parent = currentSuite ?? rootHooks
+  if (parent.beforeEach) suite.beforeEach = parent.beforeEach
+  if (parent.afterEach) suite.afterEach = parent.afterEach
+  if (parent.beforeAll) suite.beforeAll = parent.beforeAll
+  if (parent.afterAll) suite.afterAll = parent.afterAll
+
+  let insertedAt = rootSuites.length
+  rootSuites.push(suite)
+  let prevSuite = currentSuite
+  currentSuite = suite
+  try {
+    fn()
+  } catch (error) {
+    // Remove this suite and any suites registered during fn() so they don't
+    // end up in the executor after a failed registration call
+    rootSuites.splice(insertedAt)
+    throw error
+  } finally {
+    currentSuite = prevSuite
+  }
+}
+
+/**
+ * Groups related tests into a named suite. Suites can be nested snd will be displayed
+ * as such or joined with ` > ` in reporter output. Lifecycle hooks registered inside
+ * a `describe` block apply only to tests within that block.
+ *
+ * @example
+ * describe('auth', () => {
+ *   it('logs in', async () => { ... })
+ * })
+ *
+ * // Modifiers
+ * describe.skip('skipped suite', () => { ... })
+ * describe.only('focused suite', () => { ... })
+ * describe.todo('planned suite')
+ *
+ * @param name - The suite name shown in reporter output.
+ * @param fn - A function that registers the tests and lifecycle hooks in this suite.
+ */
+export const describe = Object.assign(
+  (name: string, metaOrFn: SuiteMeta | (() => void), fn?: () => void) => {
+    let meta = typeof metaOrFn === 'function' ? {} : metaOrFn
+    let suiteFn = typeof metaOrFn === 'function' ? metaOrFn : fn!
+    registerDescribe(name, suiteFn, meta)
+  },
+  {
+    skip: (name: string, fn: () => void) => registerDescribe(name, fn, { skip: true }),
+    only: (name: string, fn: () => void) => registerDescribe(name, fn, { only: true }),
+    todo: (name: string) => {
+      let fullName = currentSuite ? `${currentSuite.name} > ${name}` : name
+      if (rootSuites.some((s) => s.name === fullName)) {
+        throw new Error(`Duplicate suite name: "${fullName}"`)
+      }
+      rootSuites.push({ name: fullName, tests: [], todo: true })
+    },
+  },
+)
+
+type SuiteMeta = { skip?: boolean; only?: boolean }
+type TestMeta = { skip?: boolean; only?: boolean }
+type TestFn = (t: TestContext) => void | Promise<void>
+
+function registerIt(name: string, fn: TestFn, flags?: { only?: boolean; skip?: boolean }) {
+  let suite = currentSuite ?? getImplicitRootSuite()
+  if (suite.tests.some((t) => t.name === name)) {
+    throw new Error(`Duplicate test name: "${name}" in suite "${suite.name || 'Global'}"`)
+  }
+  suite.tests.push({ name, fn, suite, ...flags })
+}
+
+/**
+ * Defines a single test case. The optional `TestContext` argument `t` provides
+ * mock helpers and per-test cleanup registration.
+ *
+ * @example
+ * it('returns 200 for the home route', async () => {
+ *   const res = await router.fetch('/')
+ *   assert.equal(res.status, 200)
+ * })
+ *
+ * // Modifiers
+ * it.skip('not ready yet', () => { ... })
+ * it.only('focused test', () => { ... })
+ * it.todo('coming soon')
+ *
+ * @param name - The test name shown in reporter output.
+ * @param fn - The test body, receiving a {@link TestContext} as its first argument.
+ */
+export const it = Object.assign(
+  (name: string, metaOrFn: TestMeta | TestFn, fn?: TestFn) => {
+    let meta = typeof metaOrFn === 'function' ? {} : metaOrFn
+    let testFn = typeof metaOrFn === 'function' ? metaOrFn : fn!
+    registerIt(name, testFn, meta)
+  },
+  {
+    skip: (name: string, fn?: TestFn) => registerIt(name, fn ?? (() => {}), { skip: true }),
+    only: (name: string, fn: TestFn) => registerIt(name, fn, { only: true }),
+    todo: (name: string) => {
+      let suite = currentSuite ?? getImplicitRootSuite()
+      if (suite.tests.some((t) => t.name === name)) {
+        throw new Error(`Duplicate test name: "${name}" in suite "${suite.name || 'Global'}"`)
+      }
+      suite.tests.push({ name, fn: () => {}, suite, todo: true })
+    },
+  },
+)
+
+/** Alias for {@link describe}. */
+export const suite = describe
+/** Alias for {@link it}. */
+export const test = it
+
+function chainBefore(
+  existing: (() => void | Promise<void>) | undefined,
+  fn: () => void | Promise<void>,
+) {
+  return existing
+    ? async () => {
+        await existing()
+        await fn()
+      }
+    : fn
+}
+
+function chainAfter(
+  existing: (() => void | Promise<void>) | undefined,
+  fn: () => void | Promise<void>,
+) {
+  // Child/later runs first, then earlier (reverse order)
+  return existing
+    ? async () => {
+        await fn()
+        await existing()
+      }
+    : fn
+}
+
+/**
+ * Registers a hook that runs before **each** test in the current suite (or
+ * globally if called outside a `describe`). Multiple calls are chained in
+ * registration order.
+ *
+ * @param fn - The setup function to run before each test.
+ */
+export function beforeEach(fn: () => void | Promise<void>) {
+  let target = currentSuite ?? rootHooks
+  target.beforeEach = chainBefore(target.beforeEach, fn)
+}
+
+/**
+ * Registers a hook that runs after **each** test in the current suite (or
+ * globally if called outside a `describe`). Multiple calls are chained in
+ * reverse registration order.  To run logic after a singular test, use
+ * `t.after()` from the {@link TestContext}
+ *
+ * @param fn - The teardown function to run after each test.
+ */
+export function afterEach(fn: () => void | Promise<void>) {
+  let target = currentSuite ?? rootHooks
+  target.afterEach = chainAfter(target.afterEach, fn)
+}
+
+/**
+ * Registers a hook that runs once before **all** tests in the current suite
+ * (or globally if called outside a `describe`). Multiple calls are chained in
+ * registration order.
+ *
+ * @param fn - The setup function to run once before all tests in the suite.
+ */
+export function beforeAll(fn: () => void | Promise<void>) {
+  let target = currentSuite ?? rootHooks
+  target.beforeAll = chainBefore(target.beforeAll, fn)
+}
+
+/**
+ * Registers a hook that runs once after **all** tests in the current suite (or
+ * globally if called outside a `describe`). Multiple calls are chained in
+ * reverse registration order.
+ *
+ * @param fn - The teardown function to run once after all tests in the suite.
+ */
+export function afterAll(fn: () => void | Promise<void>) {
+  let target = currentSuite ?? rootHooks
+  target.afterAll = chainAfter(target.afterAll, fn)
+}
+
+/** Alias for {@link beforeAll} — matches the `node:test` API. */
+export const before = beforeAll
+/** Alias for {@link afterAll} — matches the `node:test` API. */
+export const after = afterAll

package/src/lib/mock.ts

@@ -0,0 +1,89 @@
+/** Records the arguments, return value, and any thrown error for a single call. */
+export interface MockCall<Args extends unknown[] = unknown[], Result = unknown> {
+  arguments: Args
+  result?: Result
+  error?: unknown
+}
+
+/**
+ * Metadata attached to every mock/spy function via its `.mock` property.
+ * `restore` is present on spies and reverts the original method when called.
+ */
+export interface MockContext<Args extends unknown[] = unknown[], Result = unknown> {
+  calls: MockCall<Args, Result>[]
+  restore?: () => void
+}
+
+/** A function augmented with a `.mock` property for inspecting recorded calls. */
+export type MockFunction<T extends (...args: any[]) => any = (...args: any[]) => any> = T & {
+  mock: MockContext<Parameters<T>, ReturnType<T>>
+}
+
+function createMockFn<T extends (...args: any[]) => any>(impl?: T): MockFunction<T> {
+  let calls: MockCall<Parameters<T>, ReturnType<T>>[] = []
+
+  let fn = function (this: unknown, ...args: Parameters<T>): ReturnType<T> {
+    let call: MockCall<Parameters<T>, ReturnType<T>> = { arguments: args }
+    calls.push(call)
+    if (impl) {
+      try {
+        let result = impl.apply(this, args)
+        call.result = result
+        return result
+      } catch (error) {
+        call.error = error
+        throw error
+      }
+    }
+    return undefined as ReturnType<T>
+  } as MockFunction<T>
+
+  fn.mock = { calls }
+  return fn
+}
+
+function createMethodMock<T extends object, K extends keyof T>(
+  obj: T,
+  method: K,
+  impl?: T[K] extends (...args: any[]) => any ? (...args: Parameters<T[K]>) => any : never,
+): MockFunction {
+  let original = obj[method]
+  let effectiveImpl = (impl ?? original) as (...args: any[]) => any
+  let mockFn = createMockFn(effectiveImpl)
+  obj[method] = mockFn as unknown as T[K]
+  mockFn.mock.restore = () => {
+    obj[method] = original
+  }
+  return mockFn
+}
+
+/**
+ * Utilities for creating mock functions and method spies. Mirrors the names
+ * on Node.js's built-in `MockTracker` from `node:test`.
+ *
+ * @example
+ * // Standalone mock
+ * const fn = mock.fn((x: number) => x * 2)
+ * fn(3)
+ * assert.equal(fn.mock.calls[0].result, 6)
+ *
+ * // Mock an existing method
+ * const spy = mock.method(console, 'log')
+ * console.log('hello')
+ * assert.equal(spy.mock.calls.length, 1)
+ * spy.mock.restore?.()
+ */
+export const mock = {
+  /**
+   * Creates a mock function that records every call. If `impl` is provided it
+   * is used as the underlying implementation; otherwise the mock returns
+   * `undefined`.
+   */
+  fn: createMockFn,
+  /**
+   * Replaces `obj[methodName]` with a mock and records every call. The
+   * original method is used as the implementation unless `impl` is provided.
+   * Call `mockFn.mock.restore()` to revert.
+   */
+  method: createMethodMock,
+}

package/src/lib/playwright.ts

@@ -0,0 +1,102 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs/promises'
+import { chromium, firefox, webkit } from 'playwright'
+import type { BrowserContextOptions, LaunchOptions } from 'playwright'
+import type { PlaywrightTestConfig } from 'playwright/test'
+import { tsImport } from 'tsx/esm/api'
+
+export type PlaywrightUseOpts = PlaywrightTestConfig['use']
+
+export async function loadPlaywrightConfig(
+  input: string | undefined,
+): Promise<PlaywrightTestConfig | undefined> {
+  let candidates = input
+    ? [path.resolve(process.cwd(), input)]
+    : [
+        path.join(process.cwd(), 'playwright.config.ts'),
+        path.join(process.cwd(), 'playwright.config.js'),
+      ]
+
+  for (let configPath of candidates) {
+    try {
+      await fs.access(configPath)
+      let mod = await tsImport(configPath, { parentURL: import.meta.url })
+      return mod.default ?? mod
+    } catch {
+      // not found or failed to load — try next
+    }
+  }
+}
+
+const launchers = {
+  chromium,
+  firefox,
+  webkit,
+}
+
+export function getBrowserLauncher(playwrightUseOpts?: PlaywrightUseOpts) {
+  if (playwrightUseOpts?.browserName) {
+    let launcher = launchers[playwrightUseOpts.browserName as keyof typeof launchers]
+    if (!launcher) {
+      let supportedBrowsers = Object.keys(launchers).join(', ')
+      throw new Error(
+        `Unsupported browser "${playwrightUseOpts.browserName}". ` +
+          `Supported browsers are: ${supportedBrowsers}`,
+      )
+    }
+    return launcher
+  }
+  return chromium
+}
+
+export function resolveProjects(
+  config?: PlaywrightTestConfig,
+): Array<{ name?: string; playwrightUseOpts: PlaywrightUseOpts }> {
+  if (config?.projects?.length) {
+    return config.projects.map((p) => ({
+      name: p.name,
+      playwrightUseOpts: { ...config.use, ...p.use },
+    }))
+  }
+  return [
+    {
+      name: 'chromium',
+      playwrightUseOpts: config?.use,
+    },
+  ]
+}
+
+export function getPlaywrightLaunchOptions(playwrightUseOpts?: PlaywrightUseOpts): LaunchOptions {
+  return {
+    headless: playwrightUseOpts?.headless,
+    channel: playwrightUseOpts?.channel,
+  }
+}
+
+export function getPlaywrightPageOptions(
+  playwrightUseOpts?: PlaywrightUseOpts,
+): BrowserContextOptions & { navigationTimeout?: number; actionTimeout?: number } {
+  return {
+    // Context options passed to browser.newPage()
+    bypassCSP: playwrightUseOpts?.bypassCSP,
+    colorScheme: playwrightUseOpts?.colorScheme,
+    deviceScaleFactor: playwrightUseOpts?.deviceScaleFactor,
+    extraHTTPHeaders: playwrightUseOpts?.extraHTTPHeaders,
+    geolocation: playwrightUseOpts?.geolocation,
+    hasTouch: playwrightUseOpts?.hasTouch,
+    httpCredentials: playwrightUseOpts?.httpCredentials,
+    ignoreHTTPSErrors: playwrightUseOpts?.ignoreHTTPSErrors,
+    isMobile: playwrightUseOpts?.isMobile,
+    javaScriptEnabled: playwrightUseOpts?.javaScriptEnabled,
+    locale: playwrightUseOpts?.locale,
+    offline: playwrightUseOpts?.offline,
+    permissions: playwrightUseOpts?.permissions,
+    storageState: playwrightUseOpts?.storageState,
+    timezoneId: playwrightUseOpts?.timezoneId,
+    userAgent: playwrightUseOpts?.userAgent,
+    viewport: playwrightUseOpts?.viewport,
+    // Additional options set on the page instance
+    navigationTimeout: playwrightUseOpts?.navigationTimeout,
+    actionTimeout: playwrightUseOpts?.actionTimeout,
+  }
+}

package/src/lib/reporters/dot.ts

@@ -0,0 +1,57 @@
+import { colors, normalizeLine, type Counts } from '../utils.ts'
+import type { TestResult, TestResults } from '../executor.ts'
+import type { Reporter } from './index.ts'
+
+export class DotReporter implements Reporter {
+  #failures: { name: string; error: TestResult['error'] }[] = []
+  #dotCount = 0
+
+  onSectionStart(_label: string) {}
+
+  onResult(results: TestResults, _env?: string) {
+    for (let test of results.tests) {
+      if (test.status === 'passed') {
+        process.stdout.write(colors.green('.'))
+      } else if (test.status === 'skipped') {
+        process.stdout.write(colors.dim('S'))
+      } else if (test.status === 'todo') {
+        process.stdout.write(colors.dim('T'))
+      } else {
+        process.stdout.write(colors.red('F'))
+        this.#failures.push({ name: `${test.suiteName} > ${test.name}`, error: test.error })
+      }
+      this.#dotCount++
+    }
+  }
+
+  onSummary(counts: Counts, durationMs: number) {
+    if (this.#dotCount > 0) console.log()
+
+    for (let i = 0; i < this.#failures.length; i++) {
+      let { name, error } = this.#failures[i]
+      console.log(`\n  ${colors.red(`${i + 1})`)} ${name}`)
+      if (error) {
+        console.log(`     ${colors.red(error.message)}`)
+        if (error.stack) {
+          let frames = error.stack
+            .split('\n')
+            .slice(1, 4)
+            .map((l) => `     ${normalizeLine(l).trim()}`)
+            .join('\n')
+          console.log(frames)
+        }
+      }
+    }
+
+    let { passed, failed, skipped, todo } = counts
+    let info = colors.cyan('ℹ')
+    console.log()
+    console.log(`${info} tests ${passed + failed + skipped + todo}`)
+    console.log(`${info} pass ${passed}`)
+    console.log(`${info} fail ${failed}`)
+    if (skipped > 0) console.log(`${info} skipped ${skipped}`)
+    if (todo > 0) console.log(`${info} todo ${todo}`)
+    console.log(`${info} duration_ms ${durationMs.toFixed(5)}`)
+    console.log()
+  }
+}

package/src/lib/reporters/files.ts

@@ -0,0 +1,76 @@
+import * as path from 'node:path'
+import { colors, normalizeLine, type Counts } from '../utils.ts'
+import type { TestResult, TestResults } from '../executor.ts'
+import type { Reporter } from './index.ts'
+
+export class FilesReporter implements Reporter {
+  #failures: { suiteName: string; name: string; error: TestResult['error'] }[] = []
+
+  onSectionStart(_label: string) {}
+
+  onResult(results: TestResults, env?: string) {
+    let filePath = results.tests[0]?.filePath
+    let fileName = filePath ? path.relative(process.cwd(), filePath) : '(unknown)'
+    let envLabel = env ? ` ${colors.dim(`[${env}]`)}` : ''
+    let totalDuration = results.tests.reduce((sum, t) => sum + t.duration, 0)
+    let hasFailed = results.tests.some((t) => t.status === 'failed')
+
+    let fileColor = hasFailed ? colors.red : colors.green
+    let duration = hasFailed ? '' : ` (${totalDuration.toFixed(2)}ms)`
+    console.log(`${colors.dim('▶')} ${fileColor(fileName)}${duration}${envLabel}`)
+
+    if (hasFailed) {
+      // Print failing tests with suite/test nesting using > separators
+      for (let test of results.tests) {
+        if (test.status !== 'failed') continue
+        let fullName = test.name ? `${test.suiteName} > ${test.name}` : test.suiteName
+        console.log(`  ${colors.red('✗')} ${fullName}`)
+        if (test.error) {
+          console.log(`    ${colors.red(`Error: ${test.error.message}`)}`)
+          if (test.error.stack) {
+            let stack = test.error.stack
+              .split('\n')
+              .map((line) => normalizeLine(line))
+              .join('\n')
+            console.log(`      ${stack.split('\n').slice(1, 5).join(`\n      `)}`)
+          }
+        }
+        this.#failures.push({ suiteName: test.suiteName, name: test.name, error: test.error })
+      }
+    }
+  }
+
+  onSummary(counts: Counts, durationMs: number) {
+    if (this.#failures.length > 0) {
+      console.log()
+      console.log(colors.red('Failed tests:'))
+      for (let i = 0; i < this.#failures.length; i++) {
+        let { suiteName, name, error } = this.#failures[i]
+        let fullName = name ? `${suiteName} > ${name}` : suiteName
+        console.log(`\n  ${colors.red(`${i + 1})`)} ${fullName}`)
+        if (error) {
+          console.log(`     ${colors.red(error.message)}`)
+          if (error.stack) {
+            let frames = error.stack
+              .split('\n')
+              .slice(1, 4)
+              .map((l) => `     ${normalizeLine(l).trim()}`)
+              .join('\n')
+            console.log(frames)
+          }
+        }
+      }
+    }
+
+    let { passed, failed, skipped, todo } = counts
+    let info = colors.cyan('ℹ')
+    console.log()
+    console.log(`${info} tests ${passed + failed + skipped + todo}`)
+    console.log(`${info} pass ${passed}`)
+    console.log(`${info} fail ${failed}`)
+    if (skipped > 0) console.log(`${info} skipped ${skipped}`)
+    if (todo > 0) console.log(`${info} todo ${todo}`)
+    console.log(`${info} duration_ms ${durationMs.toFixed(5)}`)
+    console.log()
+  }
+}

package/src/lib/reporters/index.ts

@@ -0,0 +1,28 @@
+import type { Counts } from '../utils.ts'
+import type { TestResults } from '../executor.ts'
+import { SpecReporter } from './spec.ts'
+import { TapReporter } from './tap.ts'
+import { DotReporter } from './dot.ts'
+import { FilesReporter } from './files.ts'
+
+export interface Reporter {
+  onResult(results: TestResults, env?: string): void
+  onSummary(counts: Counts, durationMs: number): void
+  onSectionStart(label: string): void
+}
+
+export { SpecReporter, TapReporter, DotReporter, FilesReporter }
+
+export function createReporter(type: string): Reporter {
+  switch (type) {
+    case 'tap':
+      return new TapReporter()
+    case 'dot':
+      return new DotReporter()
+    case 'files':
+      return new FilesReporter()
+    case 'spec':
+    default:
+      return new SpecReporter()
+  }
+}