@remix-run/test 0.0.0 → 0.2.0

package/src/lib/config.ts

@@ -0,0 +1,377 @@
+import * as fsp from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import * as util from 'node:util'
+import type { PlaywrightTestConfig } from 'playwright/test'
+import { importModule } from './import-module.ts'
+
+export const IS_RUNNING_FROM_SRC = path.extname(new URL(import.meta.url).pathname) === '.ts'
+
+/*
+ * The root directory for the test code. Coverage URLs are emitted as
+ * `/scripts/<rel-from-rootDir>` and resolved back via the same anchor.
+ *
+ *   - In a published install: `process.cwd()`, since deps and user source all
+ *     live under it.
+ *   - In monorepo src mode: the monorepo root, computed by walking back from
+ *     the resolved `@remix-run/test` source path. `process.cwd()` doesn't work
+ *     here because workspace deps and node_modules live above the per-package
+ *     cwd.
+ */
+export function getBrowserTestRootDir(): string {
+  return IS_RUNNING_FROM_SRC
+    ? // Resolve to packages/test/src/index.ts and the pop 3 directories off to the repo root
+      path
+        .dirname(fileURLToPath(import.meta.resolve('@remix-run/test')))
+        .split(path.sep)
+        .slice(0, -3)
+        .join(path.sep)
+    : process.cwd()
+}
+
+// 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.browser': {
+    type: 'string',
+    description: 'Glob pattern for browser test files',
+  },
+  'glob.e2e': {
+    type: 'string',
+    description: 'Glob pattern for E2E test files',
+  },
+  'glob.exclude': {
+    type: 'string',
+    description: 'Glob pattern for paths to exclude from discovery',
+  },
+  '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)',
+  },
+  coverage: {
+    type: 'boolean',
+    description: 'Enable or disable coverage collection (default: false)',
+  },
+  'coverage.dir': {
+    type: 'string',
+    description: 'Directory to output coverage reports (default: .coverage)',
+  },
+  'coverage.include': {
+    type: 'string',
+    multiple: true,
+    description: 'Glob pattern(s) for files to include in coverage',
+  },
+  'coverage.exclude': {
+    type: 'string',
+    multiple: true,
+    description: 'Glob pattern(s) for files to exclude from coverage',
+  },
+  'coverage.branches': {
+    type: 'string',
+    description: 'Branches coverage threshold percentage',
+  },
+  'coverage.functions': {
+    type: 'string',
+    description: 'Functions coverage threshold percentage',
+  },
+  'coverage.lines': {
+    type: 'string',
+    description: 'Lines coverage threshold percentage',
+  },
+  'coverage.statements': {
+    type: 'string',
+    description: 'Statements coverage threshold percentage',
+  },
+  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,browser,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(),
+  coverage: {
+    dir: '.coverage',
+    include: undefined,
+    exclude: undefined,
+    statements: undefined,
+    lines: undefined,
+    branches: undefined,
+    functions: undefined,
+  },
+  glob: {
+    test: '**/*.test{,.e2e,.browser}.{ts,tsx}',
+    browser: '**/*.test.browser.{ts,tsx}',
+    e2e: '**/*.test.e2e.{ts,tsx}',
+    exclude: 'node_modules/**',
+  },
+  reporter: process.env.CI === 'true' ? 'files' : 'spec',
+  type: 'server,browser,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.browser`: Glob pattern for the subset of browser test files (--glob.browser)
+   *  - `glob.e2e`: Glob pattern for the subset of e2e test files (--glob.e2e)
+   *  - `glob.exclude`: Glob pattern for paths to exclude from discovery (--glob.exclude)
+   */
+  glob?: {
+    test?: string
+    browser?: string
+    e2e?: string
+    exclude?: string
+  }
+  /** Max number of concurrent test workers (--concurrency) */
+  concurrency?: number | string
+  /**
+   * Coverage configuration. `true` enables with defaults; an object enables with settings;
+   * `false` disables. CLI `--coverage` flag overrides the boolean aspect.
+   */
+  coverage?:
+    | boolean
+    | {
+        dir?: string
+        include?: string[]
+        exclude?: string[]
+        statements?: number | string
+        lines?: number | string
+        branches?: number | string
+        functions?: 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
+  coverage:
+    | {
+        dir: string
+        include?: string[]
+        exclude?: string[]
+        statements?: number
+        lines?: number
+        branches?: number
+        functions?: number
+      }
+    | undefined
+  glob: {
+    test: string
+    browser: string
+    e2e: string
+    exclude: string
+  }
+  playwrightConfig: string | PlaywrightTestConfig | undefined
+  project: string | undefined
+  reporter: string
+  setup: string | undefined
+  type: string
+  watch: boolean
+}
+
+export async function loadConfig(args: string[] = process.argv.slice(2), cwd = process.cwd()) {
+  let parsed = parseCliArgs(args)
+  let fileConfig = await loadConfigFile(parsed.values.config, cwd)
+  let config = resolveConfig(fileConfig, parsed)
+  return config
+}
+
+export function getRemixTestHelpText(_target: NodeJS.WriteStream = process.stdout): 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: string[]) {
+  return util.parseArgs({ args, options: cliOptions, allowPositionals: true })
+}
+
+function resolveConfig(
+  fileConfig: RemixTestConfig,
+  { values: cliValues, positionals }: ReturnType<typeof parseCliArgs>,
+): ResolvedRemixTestConfig {
+  let fileCoverage = typeof fileConfig.coverage === 'boolean' ? {} : fileConfig.coverage || {}
+  return {
+    glob: {
+      test:
+        positionals[0] ??
+        cliValues['glob.test'] ??
+        fileConfig.glob?.test ??
+        defaultValues.glob.test,
+      browser: cliValues['glob.browser'] ?? fileConfig.glob?.browser ?? defaultValues.glob.browser,
+      e2e: cliValues['glob.e2e'] ?? fileConfig.glob?.e2e ?? defaultValues.glob.e2e,
+      exclude: cliValues['glob.exclude'] ?? fileConfig.glob?.exclude ?? defaultValues.glob.exclude,
+    },
+    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,
+    ),
+    coverage:
+      cliValues.coverage === true || !!fileConfig.coverage
+        ? {
+            dir: cliValues['coverage.dir'] ?? fileCoverage.dir ?? defaultValues.coverage!.dir,
+            include:
+              cliValues['coverage.include'] ??
+              fileCoverage.include ??
+              defaultValues.coverage!.include,
+            exclude:
+              cliValues['coverage.exclude'] ??
+              fileCoverage.exclude ??
+              defaultValues.coverage!.exclude,
+            statements:
+              cliValues['coverage.statements'] !== undefined
+                ? Number(cliValues['coverage.statements'])
+                : fileCoverage.statements !== undefined
+                  ? Number(fileCoverage.statements)
+                  : undefined,
+            lines:
+              cliValues['coverage.lines'] !== undefined
+                ? Number(cliValues['coverage.lines'])
+                : fileCoverage.lines !== undefined
+                  ? Number(fileCoverage.lines)
+                  : undefined,
+            branches:
+              cliValues['coverage.branches'] !== undefined
+                ? Number(cliValues['coverage.branches'])
+                : fileCoverage.branches !== undefined
+                  ? Number(fileCoverage.branches)
+                  : undefined,
+            functions:
+              cliValues['coverage.functions'] !== undefined
+                ? Number(cliValues['coverage.functions'])
+                : fileCoverage.functions !== undefined
+                  ? Number(fileCoverage.functions)
+                  : undefined,
+          }
+        : undefined,
+    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 | undefined,
+  cwd: string,
+): Promise<RemixTestConfig> {
+  let candidates = configPath
+    ? [path.resolve(cwd, configPath)]
+    : [path.join(cwd, 'remix-test.config.ts'), path.join(cwd, 'remix-test.config.js')]
+
+  for (let candidate of candidates) {
+    try {
+      await fsp.access(candidate)
+      let mod = await importModule(candidate, import.meta)
+      return mod.default ?? mod
+    } catch {
+      // not found or failed to load — try next
+    }
+  }
+
+  return {}
+}

package/src/lib/context.ts

@@ -0,0 +1,168 @@
+import type { Browser, Page } from 'playwright'
+import type { V8CoverageEntry } from './coverage.ts'
+import { createFakeTimers, type FakeTimers } from './fake-timers.ts'
+import { mock, type MockCall, type MockContext, type MockFunction } from './mock.ts'
+import type { getPlaywrightPageOptions } from './playwright.ts'
+
+/**
+ * The shape `t.serve()` consumes. Matches the result of `createTestServer`
+ * from `@remix-run/node-fetch-server/test`, but any object with a `baseUrl`
+ * and async `close()` works.
+ */
+export interface TestServer {
+  baseUrl: string
+  close(): Promise<void>
+}
+
+/**
+ * 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
+  }
+
+  /**
+   * Activates fake timers for testing time-dependent code.
+   *
+   * @returns {FakeTimers} A fake timers instance for controlling time
+   */
+  useFakeTimers(): FakeTimers
+
+  /**
+   * Wires a running test server up to a Playwright page so the test can drive
+   * it. The server is closed automatically when the test ends. Pair with
+   * `createTestServer` from `@remix-run/node-fetch-server/test` (or any other
+   * source of a `{ baseUrl, close }` handle) to spin up the server first.
+   *
+   * @param server - The running server the page should target
+   * @returns A `Page` whose `baseURL` is set to `server.baseUrl`.
+   */
+  serve(server: TestServer): Promise<Page>
+}
+
+export interface CreateTestContextOptions {
+  addE2ECoverageEntries: (value: { entries: V8CoverageEntry[]; baseUrl: string }) => void
+  browser: Browser
+  coverage: boolean
+  open: boolean
+  playwrightPageOptions: ReturnType<typeof getPlaywrightPageOptions>
+}
+
+export function createTestContext(options?: CreateTestContextOptions): {
+  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)
+    },
+    useFakeTimers() {
+      let timers = createFakeTimers()
+      cleanups.push(timers.restore)
+      return timers
+    },
+    async serve(server) {
+      if (!options || !options.browser) {
+        throw new Error('t.serve() is only available in E2E test suites')
+      }
+
+      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)
+      }
+
+      let coverageEnabled = options.coverage && options.browser.browserType().name() === 'chromium'
+      if (coverageEnabled) {
+        await page.coverage.startJSCoverage({ resetOnNavigation: false })
+        cleanups.push(async () => {
+          let entries = await page.coverage.stopJSCoverage()
+          options.addE2ECoverageEntries?.({
+            entries: entries as unknown as V8CoverageEntry[],
+            baseUrl: server.baseUrl,
+          })
+        })
+      }
+
+      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 { MockCall, MockContext, MockFunction }

package/src/lib/coverage-loader.ts

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { transformTypeScript } from './ts-transform.ts'
+
+// Custom ESM loader hook for TypeScript files.
+//
+// Replaces tsx's minified transformation with an un-minified esbuild transform
+// that preserves line structure. This ensures V8 coverage byte offsets map
+// cleanly to TypeScript source lines via the inline source map, giving
+// accurate per-line coverage rather than collapsing multiple statements onto
+// a single minified line.
+
+export async function load(
+  url: string,
+  context: { format?: string },
+  nextLoad: (
+    url: string,
+    context: { format?: string },
+  ) => Promise<{ format: string; source: string }>,
+) {
+  let cleanUrl = url.includes('?') ? url.slice(0, url.indexOf('?')) : url
+  if (!cleanUrl.endsWith('.ts') && !cleanUrl.endsWith('.tsx')) {
+    return nextLoad(url, context)
+  }
+
+  let filePath = fileURLToPath(cleanUrl)
+  let source = await readFile(filePath, 'utf-8')
+  let { code } = await transformTypeScript(source, filePath)
+
+  return { format: 'module', source: code, shortCircuit: true }
+}