@remix-run/test 0.1.0 → 0.3.0

package/src/lib/config.ts

@@ -1,9 +1,34 @@
+import * as fsp from 'node:fs/promises'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import * as fsp from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
 import * as util from 'node:util'
-import { tsImport } from 'tsx/esm/api'
 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
@@ -17,13 +42,25 @@ const cliOptions = {
     type: 'boolean',
     description: 'Open browser window and keep open after tests finish',
   },
+  'glob.browser': {
+    type: 'string',
+    multiple: true,
+    description: 'Glob pattern(s) for browser test files',
+  },
   'glob.e2e': {
     type: 'string',
-    description: 'Glob pattern for E2E test files',
+    multiple: true,
+    description: 'Glob pattern(s) for E2E test files',
+  },
+  'glob.exclude': {
+    type: 'string',
+    multiple: true,
+    description: 'Glob pattern(s) for paths to exclude from discovery',
   },
   'glob.test': {
     type: 'string',
-    description: 'Glob pattern for all test files',
+    multiple: true,
+    description: 'Glob pattern(s) for all test files',
   },
   concurrency: {
     type: 'string',
@@ -34,6 +71,40 @@ const cliOptions = {
     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',
@@ -46,7 +117,12 @@ const cliOptions = {
   project: {
     type: 'string',
     short: 'p',
-    description: 'Filter to a specific Playwright project (comma-separated)',
+    multiple: true,
+    description: 'Filter to specific Playwright project(s)',
+  },
+  pool: {
+    type: 'string',
+    description: 'Pool used to run server and E2E test files: forks, threads (default: forks)',
   },
   reporter: {
     type: 'string',
@@ -56,7 +132,8 @@ const cliOptions = {
   type: {
     type: 'string',
     short: 't',
-    description: 'Comma-separated test types to run (default: server,e2e)',
+    multiple: true,
+    description: 'Test types to run (default: server, browser, e2e)',
   },
   watch: {
     type: 'boolean',
@@ -71,17 +148,31 @@ const defaultValues: ResolvedRemixTestConfig = {
     open: false,
   },
   concurrency: os.availableParallelism(),
+  coverage: {
+    dir: '.coverage',
+    include: undefined,
+    exclude: undefined,
+    statements: undefined,
+    lines: undefined,
+    branches: undefined,
+    functions: undefined,
+  },
   glob: {
-    test: '**/*.test?(.e2e).{ts,tsx}',
-    e2e: '**/*.test.e2e.{ts,tsx}',
+    test: ['**/*.test{,.e2e,.browser}.{ts,tsx}'],
+    browser: ['**/*.test.browser.{ts,tsx}'],
+    e2e: ['**/*.test.e2e.{ts,tsx}'],
+    exclude: ['node_modules/**'],
   },
-  reporter: process.env.CI === 'true' ? 'dot' : 'spec',
-  type: 'server,e2e',
-  setup: undefined,
+  pool: 'forks',
   playwrightConfig: undefined,
   project: undefined,
+  reporter: process.env.CI === 'true' ? 'files' : 'spec',
+  setup: undefined,
+  type: ['server', 'browser', 'e2e'],
   watch: false,
-} as const
+}
+
+export type RemixTestPool = 'forks' | 'threads'
 
 export interface RemixTestConfig {
   /**
@@ -94,16 +185,36 @@ export interface RemixTestConfig {
     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 patterns to identify test files. Each field accepts a single pattern
+   * or an array of patterns; arrays are unioned during discovery.
+   *  - `glob.test`: Glob pattern(s) for all test files (--glob.test)
+   *  - `glob.browser`: Glob pattern(s) for the subset of browser test files (--glob.browser)
+   *  - `glob.e2e`: Glob pattern(s) for the subset of e2e test files (--glob.e2e)
+   *  - `glob.exclude`: Glob pattern(s) for paths to exclude from discovery (--glob.exclude)
    */
   glob?: {
-    test?: string
-    e2e?: string
+    test?: string | string[]
+    browser?: string | string[]
+    e2e?: string | string[]
+    exclude?: string | 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 | string[]
+        exclude?: string | 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)
@@ -114,12 +225,23 @@ export interface RemixTestConfig {
    * 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
+  /**
+   * Pool used to run server and E2E test files. Forked child processes are the default,
+   * but worker threads are available for projects that prefer the previous behavior.
+   */
+  pool?: RemixTestPool
+  /**
+   * Filter tests to specific playwright project(s) (--project). Accepts a single
+   * project name or an array of names; `--project` may be repeated on the CLI.
+   */
+  project?: string | string[]
   /** Test reporter (--reporter) */
   reporter?: string
-  /** Comma-separated list of test types to run (--type) */
-  type?: string
+  /**
+   * Test type(s) to run (--type). Accepts a single type or an array of types;
+   * `--type` may be repeated on the CLI. Valid values: "server", "browser", "e2e".
+   */
+  type?: string | string[]
   /** Watch mode — re-run tests on file changes (--watch) */
   watch?: boolean
 }
@@ -130,36 +252,45 @@ export interface ResolvedRemixTestConfig {
     open?: boolean
   }
   concurrency: number
+  coverage:
+    | {
+        dir: string
+        include?: string[]
+        exclude?: string[]
+        statements?: number
+        lines?: number
+        branches?: number
+        functions?: number
+      }
+    | undefined
   glob: {
-    test: string
-    e2e: string
+    test: string[]
+    browser: string[]
+    e2e: string[]
+    exclude: string[]
   }
   playwrightConfig: string | PlaywrightTestConfig | undefined
-  project: string | undefined
+  project: string[] | undefined
   reporter: string
+  pool: RemixTestPool
   setup: string | undefined
-  type: string
+  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)
+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
 }
 
-function generateHelp(): string {
+export function getRemixTestHelpText(_target: NodeJS.WriteStream = process.stdout): string {
   let lines = [
-    'Usage: remix-test [glob] [options]',
+    'Usage: remix-test [glob...] [options]',
     '',
     'Arguments:',
-    `  glob                     Glob pattern for test files (default: "${defaultValues.glob.test}")`,
+    `  glob                     Glob pattern(s) for test files (default: "${defaultValues.glob.test.join(', ')}")`,
     '',
     'Options:',
   ]
@@ -175,22 +306,42 @@ function generateHelp(): string {
   return lines.join('\n')
 }
 
-function parseCliArgs(args = process.argv.slice(2)) {
+function parseCliArgs(args: string[]) {
   return util.parseArgs({ args, options: cliOptions, allowPositionals: true })
 }
 
+function toArray<T>(value: T | readonly T[]): T[] {
+  return Array.isArray(value) ? [...value] : [value as T]
+}
+
+function toCommaSeparatedArray(value: string | readonly string[]): string[] {
+  return toArray(value).flatMap((item) =>
+    item
+      .split(',')
+      .map((part) => part.trim())
+      .filter(Boolean),
+  )
+}
+
 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,
-      e2e: cliValues['glob.e2e'] ?? fileConfig.glob?.e2e ?? defaultValues.glob.e2e,
+      test: toArray(
+        positionals.length > 0
+          ? positionals
+          : (cliValues['glob.test'] ?? fileConfig.glob?.test ?? defaultValues.glob.test),
+      ),
+      browser: toArray(
+        cliValues['glob.browser'] ?? fileConfig.glob?.browser ?? defaultValues.glob.browser,
+      ),
+      e2e: toArray(cliValues['glob.e2e'] ?? fileConfig.glob?.e2e ?? defaultValues.glob.e2e),
+      exclude: toArray(
+        cliValues['glob.exclude'] ?? fileConfig.glob?.exclude ?? defaultValues.glob.exclude,
+      ),
     },
     browser: {
       echo: cliValues['browser.echo'] ?? fileConfig.browser?.echo ?? defaultValues.browser.echo,
@@ -199,32 +350,93 @@ function resolveConfig(
     concurrency: Number(
       cliValues.concurrency ?? fileConfig.concurrency ?? defaultValues.concurrency,
     ),
+    coverage:
+      cliValues.coverage === true || !!fileConfig.coverage
+        ? {
+            dir: cliValues['coverage.dir'] ?? fileCoverage.dir ?? defaultValues.coverage!.dir,
+            include: (() => {
+              let raw =
+                cliValues['coverage.include'] ??
+                fileCoverage.include ??
+                defaultValues.coverage!.include
+              return raw === undefined ? undefined : toArray(raw)
+            })(),
+            exclude: (() => {
+              let raw =
+                cliValues['coverage.exclude'] ??
+                fileCoverage.exclude ??
+                defaultValues.coverage!.exclude
+              return raw === undefined ? undefined : toArray(raw)
+            })(),
+            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,
+    pool: resolvePool(cliValues.pool ?? fileConfig.pool ?? defaultValues.pool),
+    project: (() => {
+      let raw = cliValues.project ?? fileConfig.project ?? defaultValues.project
+      return raw === undefined ? undefined : toCommaSeparatedArray(raw)
+    })(),
     reporter: cliValues.reporter ?? fileConfig.reporter ?? defaultValues.reporter,
-    type: cliValues.type ?? fileConfig.type ?? defaultValues.type,
+    type: toCommaSeparatedArray(cliValues.type ?? fileConfig.type ?? defaultValues.type),
     watch: cliValues.watch ?? fileConfig.watch ?? defaultValues.watch,
   }
 }
 
-async function loadConfigFile(configPath?: string): Promise<RemixTestConfig> {
+function resolvePool(value: string): RemixTestPool {
+  if (value === 'forks' || value === 'threads') {
+    return value
+  }
+
+  throw new Error(`Unsupported test pool "${value}". Supported pools are: forks, threads`)
+}
+
+async function loadConfigFile(
+  configPath: string | undefined,
+  cwd: 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'),
-      ]
+    ? [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 tsImport(candidate, { parentURL: import.meta.url })
-      return mod.default ?? mod
     } catch {
-      // not found or failed to load — try next
+      // not found — try the next candidate
+      continue
     }
+    // The file exists; let import errors propagate rather than silently
+    // falling through to defaults — that masking is what hid "Windows
+    // absolute paths aren't valid ESM specifiers" by classifying every
+    // browser test as a server test.
+    let mod = await importModule(candidate, import.meta)
+    return mod.default ?? mod
   }
 
   return {}

package/src/lib/context.ts

@@ -1,9 +1,19 @@
 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 { 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.
@@ -58,20 +68,36 @@ export interface TestContext {
   }
 
   /**
-   * Starts a test server with the provided request handler.
+   * 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 {(req: Request) => Promise<Response>} handler - Function handling incoming requests
-   * @returns {Promise<Page>} A promise resolving to a page instance for the server
+   * @param server - The running server the page should target
+   * @returns A `Page` whose `baseURL` is set to `server.baseUrl`.
    */
-  serve(handler: (req: Request) => Promise<Response>): Promise<Page>
+  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: {
-  createServer?: CreateServerFunction
-  browser?: Browser
-  open?: boolean
-  playwrightPageOptions?: ReturnType<typeof getPlaywrightPageOptions>
-}): { testContext: TestContext; cleanup(): Promise<void> } {
+export function createTestContext(options?: CreateTestContextOptions): {
+  testContext: TestContext
+  cleanup(): Promise<void>
+} {
   let cleanups: Array<() => void | Promise<void>> = []
 
   let testContext: TestContext = {
@@ -86,12 +112,16 @@ export function createTestContext(options: {
     after(fn) {
       cleanups.push(fn)
     },
-    async serve(handler) {
-      if (!options.createServer || !options.browser) {
+    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 server = await options.createServer(handler)
       let page = await options.browser.newPage({
         ...options.playwrightPageOptions,
         baseURL: server.baseUrl,
@@ -103,6 +133,18 @@ export function createTestContext(options: {
         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()
@@ -123,4 +165,4 @@ export function createTestContext(options: {
   }
 }
 
-export type { MockFunction, MockCall, MockContext }
+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 }
+}