@remix-run/test 0.1.0 → 0.2.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,10 +42,18 @@ const cliOptions = {
     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',
@@ -34,6 +67,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',
@@ -56,7 +123,7 @@ const cliOptions = {
   type: {
     type: 'string',
     short: 't',
-    description: 'Comma-separated test types to run (default: server,e2e)',
+    description: 'Comma-separated test types to run (default: server,browser,e2e)',
   },
   watch: {
     type: 'boolean',
@@ -71,12 +138,23 @@ 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}',
+    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',
+  reporter: process.env.CI === 'true' ? 'files' : 'spec',
+  type: 'server,browser,e2e',
   setup: undefined,
   playwrightConfig: undefined,
   project: undefined,
@@ -96,14 +174,33 @@ export interface RemixTestConfig {
   /**
    * 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)
@@ -130,9 +227,22 @@ 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
+    browser: string
     e2e: string
+    exclude: string
   }
   playwrightConfig: string | PlaywrightTestConfig | undefined
   project: string | undefined
@@ -142,19 +252,14 @@ export interface ResolvedRemixTestConfig {
   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]',
     '',
@@ -175,7 +280,7 @@ 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 })
 }
 
@@ -183,6 +288,7 @@ function resolveConfig(
   fileConfig: RemixTestConfig,
   { values: cliValues, positionals }: ReturnType<typeof parseCliArgs>,
 ): ResolvedRemixTestConfig {
+  let fileCoverage = typeof fileConfig.coverage === 'boolean' ? {} : fileConfig.coverage || {}
   return {
     glob: {
       test:
@@ -190,7 +296,9 @@ function resolveConfig(
         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,
@@ -199,6 +307,44 @@ 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:
+              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,
@@ -209,18 +355,18 @@ function resolveConfig(
   }
 }
 
-async function loadConfigFile(configPath?: string): Promise<RemixTestConfig> {
+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 })
+      let mod = await importModule(candidate, import.meta)
       return mod.default ?? mod
     } catch {
       // not found or failed to load — try next

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 }
+}