@remix-run/test 0.0.0 → 0.1.0

package/src/lib/config.ts

@@ -0,0 +1,231 @@
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as fsp from 'node:fs/promises'
+import * as util from 'node:util'
+import { tsImport } from 'tsx/esm/api'
+import type { PlaywrightTestConfig } from 'playwright/test'
+
+// prettier-ignore
+// Note: `description` is not a field used by parseArgs(), it's an additional field
+// we use for `--help`
+const cliOptions = {
+  'browser.echo': {
+    type: 'boolean',
+    description: 'Echo browser console output to stdout',
+  },
+  'browser.open': {
+    type: 'boolean',
+    description: 'Open browser window and keep open after tests finish',
+  },
+  'glob.e2e': {
+    type: 'string',
+    description: 'Glob pattern for E2E test files',
+  },
+  'glob.test': {
+    type: 'string',
+    description: 'Glob pattern for all test files',
+  },
+  concurrency: {
+    type: 'string',
+    short: 'c',
+    description: 'Max number of concurrent test workers (default: os.availableParallelism())',
+  },
+  config: {
+    type: 'string',
+    description: 'Path to config file (default: remix-test.config.ts)',
+  },
+  setup: {
+    type: 'string',
+    short: 's',
+    description: 'Path to a setup module exporting globalSetup/globalTeardown',
+  },
+  playwrightConfig: {
+    type: 'string',
+    description: 'Path to a Playwright config file',
+  },
+  project: {
+    type: 'string',
+    short: 'p',
+    description: 'Filter to a specific Playwright project (comma-separated)',
+  },
+  reporter: {
+    type: 'string',
+    short: 'r',
+    description: 'Test reporter: spec, files, tap, dot (default: spec)',
+  },
+  type: {
+    type: 'string',
+    short: 't',
+    description: 'Comma-separated test types to run (default: server,e2e)',
+  },
+  watch: {
+    type: 'boolean',
+    short: 'w',
+    description: 'Re-run tests on file changes',
+  },
+} as const
+
+const defaultValues: ResolvedRemixTestConfig = {
+  browser: {
+    echo: false,
+    open: false,
+  },
+  concurrency: os.availableParallelism(),
+  glob: {
+    test: '**/*.test?(.e2e).{ts,tsx}',
+    e2e: '**/*.test.e2e.{ts,tsx}',
+  },
+  reporter: process.env.CI === 'true' ? 'dot' : 'spec',
+  type: 'server,e2e',
+  setup: undefined,
+  playwrightConfig: undefined,
+  project: undefined,
+  watch: false,
+} as const
+
+export interface RemixTestConfig {
+  /**
+   * Options for controlling the playwright browser
+   *  - `browser.echo`: Echo browser console output to stdout (--browser.echo)
+   *  - `browser.open`: Open browser window and keep open after test finish (--browser.open)
+   */
+  browser?: {
+    echo?: boolean
+    open?: boolean
+  }
+  /**
+   * Glob patterns to identify test files
+   *  - `glob.test`: Glob pattern for all test files (--glob.test)
+   *  - `glob.e2e`: Glob pattern for the subset of e2e test files (--glob.e2e)
+   */
+  glob?: {
+    test?: string
+    e2e?: string
+  }
+  /** Max number of concurrent test workers (--concurrency) */
+  concurrency?: number | string
+  /**
+   * Path to a module that exports `globalSetup` and/or `globalTeardown` functions,
+   * called once before and after the test run respectively. (--setup)
+   */
+  setup?: string
+  /**
+   * Playwright configuration — either a path to a playwright config file or an inline
+   * PlaywrightTestConfig object. CLI `--playwrightConfig` only accepts a file path.
+   */
+  playwrightConfig?: string | PlaywrightTestConfig
+  /** Filter tests to a specific playwright project or comma-separated list of projects (--project) */
+  project?: string
+  /** Test reporter (--reporter) */
+  reporter?: string
+  /** Comma-separated list of test types to run (--type) */
+  type?: string
+  /** Watch mode — re-run tests on file changes (--watch) */
+  watch?: boolean
+}
+
+export interface ResolvedRemixTestConfig {
+  browser: {
+    echo?: boolean
+    open?: boolean
+  }
+  concurrency: number
+  glob: {
+    test: string
+    e2e: string
+  }
+  playwrightConfig: string | PlaywrightTestConfig | undefined
+  project: string | undefined
+  reporter: string
+  setup: string | undefined
+  type: string
+  watch: boolean
+}
+
+export async function loadConfig() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log(generateHelp())
+    process.exit(0)
+  }
+
+  let parsed = parseCliArgs()
+  let fileConfig = await loadConfigFile(parsed.values.config)
+  let config = resolveConfig(fileConfig, parsed)
+  return config
+}
+
+function generateHelp(): string {
+  let lines = [
+    'Usage: remix-test [glob] [options]',
+    '',
+    'Arguments:',
+    `  glob                     Glob pattern for test files (default: "${defaultValues.glob.test}")`,
+    '',
+    'Options:',
+  ]
+
+  for (let [long, opt] of Object.entries(cliOptions)) {
+    let short = 'short' in opt ? `/-${opt.short}` : ''
+    let label = opt.type === 'string' ? `--${long}${short} <value>` : `--${long}${short}`
+    lines.push(`  ${label.padEnd(30)} ${opt.description}`)
+  }
+
+  lines.push(`  ${'-h, --help'.padEnd(30)} Show this help message`)
+
+  return lines.join('\n')
+}
+
+function parseCliArgs(args = process.argv.slice(2)) {
+  return util.parseArgs({ args, options: cliOptions, allowPositionals: true })
+}
+
+function resolveConfig(
+  fileConfig: RemixTestConfig,
+  { values: cliValues, positionals }: ReturnType<typeof parseCliArgs>,
+): ResolvedRemixTestConfig {
+  return {
+    glob: {
+      test:
+        positionals[0] ??
+        cliValues['glob.test'] ??
+        fileConfig.glob?.test ??
+        defaultValues.glob.test,
+      e2e: cliValues['glob.e2e'] ?? fileConfig.glob?.e2e ?? defaultValues.glob.e2e,
+    },
+    browser: {
+      echo: cliValues['browser.echo'] ?? fileConfig.browser?.echo ?? defaultValues.browser.echo,
+      open: cliValues['browser.open'] ?? fileConfig.browser?.open ?? defaultValues.browser.open,
+    },
+    concurrency: Number(
+      cliValues.concurrency ?? fileConfig.concurrency ?? defaultValues.concurrency,
+    ),
+    setup: cliValues.setup ?? fileConfig.setup ?? defaultValues.setup,
+    playwrightConfig:
+      cliValues.playwrightConfig ?? fileConfig.playwrightConfig ?? defaultValues.playwrightConfig,
+    project: cliValues.project ?? fileConfig.project ?? defaultValues.project,
+    reporter: cliValues.reporter ?? fileConfig.reporter ?? defaultValues.reporter,
+    type: cliValues.type ?? fileConfig.type ?? defaultValues.type,
+    watch: cliValues.watch ?? fileConfig.watch ?? defaultValues.watch,
+  }
+}
+
+async function loadConfigFile(configPath?: string): Promise<RemixTestConfig> {
+  let candidates = configPath
+    ? [path.resolve(process.cwd(), configPath)]
+    : [
+        path.join(process.cwd(), 'remix-test.config.ts'),
+        path.join(process.cwd(), 'remix-test.config.js'),
+      ]
+
+  for (let candidate of candidates) {
+    try {
+      await fsp.access(candidate)
+      let mod = await tsImport(candidate, { parentURL: import.meta.url })
+      return mod.default ?? mod
+    } catch {
+      // not found or failed to load — try next
+    }
+  }
+
+  return {}
+}

package/src/lib/context.ts

@@ -0,0 +1,126 @@
+import type { Browser, Page } from 'playwright'
+import { mock, type MockFunction, type MockCall, type MockContext } from './mock.ts'
+
+import type { CreateServerFunction } from './e2e-server.ts'
+import type { getPlaywrightPageOptions } from './playwright.ts'
+
+/**
+ * Test Context providing utilities for testing via remix-test.  The context is
+ * passed as the first argument to the {@link test}/{@link it} functions.
+ *
+ * @example
+ * describe('my test suite', () => {
+ *   it('my test case', async (t) => {
+ *     let mockFn = t.mock.fn(() => 'mocked value')
+ *     // ...
+ *   })
+ * })
+ */
+export interface TestContext {
+  /**
+   * Registers a cleanup function to be called after the test completes.
+   *
+   * @param {() => void} fn - The cleanup function to execute
+   * @returns {void}
+   */
+  after(fn: () => void): void
+
+  /**
+   * Mock tracker for the current test. Mirrors the shape of Node's
+   * `t.mock`. Method mocks created here are auto-restored on test completion.
+   */
+  mock: {
+    /**
+     * Creates a mock function with an optional implementation.
+     *
+     * @template T - The function type to be mocked
+     * @param {T} [impl] - Optional custom implementation for the mock
+     * @returns {MockFunction<T>} A mock function instance
+     */
+    fn<T extends (...args: any[]) => any>(impl?: T): MockFunction<T>
+
+    /**
+     * Replaces `obj[methodName]` with a mock and records every call. The
+     * original method is restored automatically after the test completes.
+     *
+     * @template T - The object type
+     * @template K - The method key of the object
+     * @param {T} obj - The object to mock
+     * @param {K} methodName - The method name to mock
+     * @param {Function} [impl] - Optional implementation override (must be a function)
+     * @returns {MockFunction} A mock function instance for the mocked method
+     */
+    method<T extends object, K extends keyof T>(
+      obj: T,
+      methodName: K,
+      impl?: Function,
+    ): MockFunction
+  }
+
+  /**
+   * Starts a test server with the provided request handler.
+   *
+   * @param {(req: Request) => Promise<Response>} handler - Function handling incoming requests
+   * @returns {Promise<Page>} A promise resolving to a page instance for the server
+   */
+  serve(handler: (req: Request) => Promise<Response>): Promise<Page>
+}
+
+export function createTestContext(options: {
+  createServer?: CreateServerFunction
+  browser?: Browser
+  open?: boolean
+  playwrightPageOptions?: ReturnType<typeof getPlaywrightPageOptions>
+}): { testContext: TestContext; cleanup(): Promise<void> } {
+  let cleanups: Array<() => void | Promise<void>> = []
+
+  let testContext: TestContext = {
+    mock: {
+      fn: mock.fn,
+      method(obj, methodName, impl) {
+        let mockFn = mock.method(obj, methodName, impl as any)
+        if (mockFn.mock.restore) cleanups.push(mockFn.mock.restore)
+        return mockFn
+      },
+    },
+    after(fn) {
+      cleanups.push(fn)
+    },
+    async serve(handler) {
+      if (!options.createServer || !options.browser) {
+        throw new Error('t.serve() is only available in E2E test suites')
+      }
+
+      let server = await options.createServer(handler)
+      let page = await options.browser.newPage({
+        ...options.playwrightPageOptions,
+        baseURL: server.baseUrl,
+      })
+      if (options.playwrightPageOptions?.navigationTimeout != null) {
+        page.setDefaultNavigationTimeout(options.playwrightPageOptions.navigationTimeout)
+      }
+      if (options.playwrightPageOptions?.actionTimeout != null) {
+        page.setDefaultTimeout(options.playwrightPageOptions.actionTimeout)
+      }
+
+      cleanups.push(async () => {
+        if (!options.open) {
+          await page.close()
+        }
+        await server.close()
+      })
+
+      return page
+    },
+  }
+
+  return {
+    testContext,
+    async cleanup() {
+      for (let fn of cleanups) await fn()
+      cleanups.length = 0
+    },
+  }
+}
+
+export type { MockFunction, MockCall, MockContext }

package/src/lib/e2e-server.ts

@@ -0,0 +1,28 @@
+import * as http from 'node:http'
+import { createRequestListener } from '@remix-run/node-fetch-server'
+
+export interface CreateServerFunction {
+  (handler: (req: Request) => Promise<Response>): Promise<{
+    baseUrl: string
+    close(): Promise<void>
+  }>
+}
+
+export function createServer(handler: (req: Request) => Promise<Response>): Promise<{
+  baseUrl: string
+  close(): Promise<void>
+}> {
+  return new Promise((resolve, reject) => {
+    let server = http.createServer(createRequestListener(handler))
+
+    server.listen(0, '127.0.0.1', () => {
+      let addr = server.address() as { port: number }
+      resolve({
+        baseUrl: `http://127.0.0.1:${addr.port}`,
+        close: () => new Promise((r, rj) => server.close((e) => (e ? rj(e) : r()))),
+      })
+    })
+
+    server.on('error', reject)
+  })
+}

package/src/lib/executor.ts

@@ -0,0 +1,162 @@
+import type { Browser, BrowserContextOptions } from 'playwright'
+import { createTestContext } from './context.ts'
+import type { CreateServerFunction } from './e2e-server.ts'
+
+export interface TestResult {
+  name: string
+  suiteName: string
+  filePath?: string
+  status: 'passed' | 'failed' | 'skipped' | 'todo'
+  error?: {
+    message: string
+    stack?: string
+  }
+  duration: number
+}
+
+export interface TestResults {
+  passed: number
+  failed: number
+  skipped: number
+  todo: number
+  tests: TestResult[]
+}
+
+export async function runTests(options?: {
+  createServer?: CreateServerFunction
+  browser?: Browser
+  open?: boolean
+  playwrightPageOptions?: BrowserContextOptions
+}): Promise<TestResults> {
+  let suites = (globalThis as any).__testSuites || []
+  let results: TestResults = {
+    passed: 0,
+    failed: 0,
+    skipped: 0,
+    todo: 0,
+    tests: [],
+  }
+
+  let hasOnlySuites = suites.some((s: any) => s.only)
+
+  for (let suite of suites) {
+    // If any suite uses .only, skip all non-only suites
+    if (hasOnlySuites && !suite.only) {
+      for (let test of suite.tests) {
+        results.tests.push({
+          name: test.name,
+          suiteName: suite.name,
+          status: 'skipped',
+          duration: 0,
+        })
+        results.skipped++
+      }
+      continue
+    }
+
+    if (suite.skip || suite.todo) {
+      let status: 'skipped' | 'todo' = suite.todo ? 'todo' : 'skipped'
+      for (let test of suite.tests) {
+        results.tests.push({ name: test.name, suiteName: suite.name, status, duration: 0 })
+        results[status]++
+      }
+      // describe.todo('name') with no tests — add placeholder so suite appears in output
+      if (suite.tests.length === 0) {
+        results.tests.push({ name: '', suiteName: suite.name, status, duration: 0 })
+        results[status]++
+      }
+      continue
+    }
+
+    if (suite.beforeAll) {
+      try {
+        await suite.beforeAll()
+      } catch (error) {
+        console.error(`beforeAll failed in suite "${suite.name}":`, error)
+        continue
+      }
+    }
+
+    let hasOnlyTests = suite.tests.some((t: any) => t.only)
+
+    for (let test of suite.tests) {
+      // If any test uses .only, skip all non-only tests in this suite
+      if (hasOnlyTests && !test.only) {
+        results.tests.push({
+          name: test.name,
+          suiteName: suite.name,
+          status: 'skipped',
+          duration: 0,
+        })
+        results.skipped++
+        continue
+      }
+
+      if (test.skip || test.todo) {
+        let status: 'skipped' | 'todo' = test.todo ? 'todo' : 'skipped'
+        results.tests.push({ name: test.name, suiteName: suite.name, status, duration: 0 })
+        results[status]++
+        continue
+      }
+
+      let startTime = performance.now()
+      let result: TestResult = {
+        name: test.name,
+        suiteName: suite.name,
+        status: 'passed',
+        duration: 0,
+      }
+
+      let { testContext, cleanup } = createTestContext({
+        createServer: options?.createServer,
+        browser: options?.browser,
+        open: options?.open,
+        playwrightPageOptions: options?.playwrightPageOptions,
+      })
+
+      try {
+        if (suite.beforeEach) {
+          await suite.beforeEach()
+        }
+
+        await test.fn(testContext)
+
+        result.status = 'passed'
+        results.passed++
+      } catch (error: any) {
+        result.status = 'failed'
+        result.error = {
+          message: error.message || String(error),
+          stack: error.stack,
+        }
+        results.failed++
+      } finally {
+        await cleanup()
+        if (suite.afterEach) {
+          try {
+            await suite.afterEach()
+          } catch (error) {
+            console.error('afterEach failed:', error)
+          }
+        }
+
+        result.duration = performance.now() - startTime
+        results.tests.push(result)
+      }
+    }
+
+    if (suite.afterAll) {
+      try {
+        await suite.afterAll()
+      } catch (error) {
+        console.error(`afterAll failed in suite "${suite.name}":`, error)
+      }
+    }
+  }
+
+  // Clear suites in-place so the shared framework module is reset
+  // for the next test file (which reuses the same cached module instance)
+  suites.length = 0
+
+  return results
+}