@remix-run/test 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,326 @@
-# Placeholder Package
+# `test`
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
+A test framework for Remix applications
+
+## Features
+
+- `describe`/`it` test structure with `before`/`after`/`beforeEach`/`afterEach` hooks
+- Server-side unit testing
+- Playwright E2E testing via `t.serve`
+- Mock functions and method spies via `t.mock.fn` / `t.mock.method`
+- Watch mode
+- Config file support (`remix-test.config.ts`)
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Write test files that import from `remix/test`:
+
+```ts
+import * as assert from 'remix/assert'
+import { describe, it } from 'remix/test'
+
+describe('My Test Suite', () => {
+  it('tests a function', () => {
+    let result = something()
+    assert.equal(result, 42)
+  })
+})
+```
+
+Run tests with the CLI:
+
+```sh
+remix-test
+```
+
+By default, `remix-test` discovers all files matching `**/*.test.{ts,tsx}`. Pass a glob as the first positional argument to override:
+
+```sh
+remix-test "src/**/*.test.ts"
+```
+
+Or, you may control via the `glob.test` config field/CLI arg.
+
+### Config File
+
+Create a `remix-test.config.ts` (or `.js`) file at the root of your project (shown with default values):
+
+```ts
+import type { RemixTestConfig } from 'remix/test'
+
+export default {
+  // Browser options for E2E tests
+  browser: {
+    // Echo browser console output to the terminal
+    echo: false,
+    // Open browser (via playwright `headless:false`) and keep it open after tests
+    // complete (useful for debugging)
+    open: false,
+  },
+
+  // Max number of concurrent test workers (default `os.availableParallelism()`)
+  concurrency: 2,
+
+  glob: {
+    // Glob pattern identifying all test files (default: "**/*.test?(.e2e).{ts,tsx}")
+    test: '**/*.test?(.e2e).ts',
+    // Global pattern identifying the subset of E2E test files{ts,tsx}")
+    e2e: '**/*.test.e2e.ts',
+  },
+
+  // Playwright configuration for E2E tests, or string path to an existing
+  // config file on disk
+  playwrightConfig: {
+    projects: [
+      { name: 'chromium', use: { browserName: 'chromium' } },
+      { name: 'firefox', use: { browserName: 'firefox' } },
+    ],
+    use: {
+      navigationTimeout: 5_000,
+      actionTimeout: 5_000,
+    },
+  },
+
+  // Comma-separated list of playwright projects to run E2E tests for
+  project: 'chromium',
+
+  // Test reporter ("spec", "files", "tap", "dot")
+  reporter: 'spec',
+
+  // Path to a setup module (see Setup section below)
+  setup: './test/setup.ts',
+
+  // Comma-separated list of test types to run ("server", "e2e")
+  type: 'server,e2e',
+
+  // Watch for file changes and re-run
+  watch: false,
+} satisfies RemixTestConfig
+```
+
+### CLI Options
+
+You can point to a different config file location with the `--config` flag:
+
+```sh
+remix-test --config ./tests/config.ts
+```
+
+You may also specify any config field as a CLI flag which will take precedence over config file values:
+
+| Flag                        | Short |
+| --------------------------- | ----- |
+| `--browser.echo`            |       |
+| `--browser.open`            |       |
+| `--concurrency <n>`         | `-c`  |
+| `--glob.test`               |       |
+| `--glob.e2e`                |       |
+| `--playwrightConfig <path>` |       |
+| `--project <name>`          | `-p`  |
+| `--reporter <name>`         | `-r`  |
+| `--setup <path>`            | `-s`  |
+| `--type <name>`             | `-t`  |
+| `--watch`                   | `-w`  |
+
+### Setup
+
+The `setup` option points to a module that can export `globalSetup` and/or `globalTeardown` functions, called once before and after the entire test run respectively:
+
+```ts
+// ./test/setup.ts
+export async function globalSetup() {
+  await db.migrate()
+}
+
+export async function globalTeardown() {
+  await db.close()
+}
+```
+
+## API
+
+### Test framework
+
+```ts
+import { beforeAll, afterAll, beforeEach, afterEach, describe, it } from 'remix/test'
+
+beforeAll(() => {})
+afterAll(() => {})
+
+describe('My Test Suite', () => {
+  beforeEach(() => {})
+  afterEach(() => {})
+
+  it('tests something', () => {})
+  it('tests something else', () => {})
+})
+```
+
+`suite` and `test` are aliases for `describe` and `it`.
+
+```ts
+import { suite, test } from 'remix/test'
+
+suite('My Test Suite', () => {
+  test('tests something', () => {})
+})
+```
+
+### Test Context
+
+Each test callback receives a `TestContext` (`t`) as its first argument with helpful test utilities.
+
+```ts
+interface TestContext {
+  // Register a cleanup function to run after the test completes
+  after(fn: () => void): void
+
+  // Mock tracker, mirroring the shape of Node's `t.mock` from `node:test`
+  mock: {
+    // Create a mock function with an optional implementation
+    fn<T extends (...args: any[]) => any>(impl?: T): MockFunction<T>
+
+    // Mock an object method with an optional implementation override
+    method<T extends object, K extends keyof T>(
+      obj: T,
+      methodName: K,
+      impl?: Function,
+    ): MockFunction
+  }
+
+  // E2E only: start a server with the given request handler, returns a Playwright Page
+  serve(handler: (req: Request) => Promise<Response>): Promise<Page>
+}
+```
+
+#### Mocks and Spies
+
+Use `t.mock.fn()`/`t.mock.method()` to set up mocks and method spies. This is preferred over the standalone `mock` import because TestContext method mocks are automatically restored after the test runs.
+
+```ts
+it('mocks and spies', (t) => {
+  // Create a mock function
+  let fn = t.mock.fn((x: number) => x * 2)
+  fn(3)
+  fn.mock.calls[0].result // 6
+
+  // Mock an existing method
+  let spy = t.mock.method(console, 'warn')
+  console.warn('test')
+  spy.mock.calls.length // 1
+  // spy is restored automatically when the test ends
+})
+```
+
+#### Cleanup
+
+You can register local test cleanup logic with `t.after()`:
+
+```ts
+it('cleanup', (t) => {
+  let conn = db.connect()
+  t.after(() => conn.close())
+  // ...
+})
+```
+
+#### E2E
+
+In E2E test files, `t.serve()` starts an HTTP server and returns a Playwright `Page`. See [E2E Testing](#e2e-testing) for details.
+
+```ts
+it('navigates to home', async (t) => {
+  let router = createRouter()
+  let page = await t.serve(router.fetch)
+  await page.goto('/')
+})
+```
+
+### Standalone mocks (module scope)
+
+When you need a mock outside of a test body, import `mock` directly and call `restore()` manually:
+
+```ts
+import { mock } from 'remix/test'
+
+let spy = mock.method(console, 'log')
+// ...
+spy.mock.restore?.()
+```
+
+### E2E Testing
+
+E2E tests use [Playwright](https://playwright.dev) and are discovered by the `**/*.test.e2e.{ts,tsx}` glob pattern (configurable via `glob.e2e`). They use the same `describe`/`it` API as unit tests.
+
+E2E tests receive `t.serve()` on the test context, which starts an HTTP server with the given request handler and returns a Playwright [`Page`](https://playwright.dev/docs/api/class-page). The server and page are automatically closed after each test.
+
+```ts
+import * as assert from 'remix/assert'
+import { describe, it } from 'remix/test'
+import { createRouter } from './router.ts'
+
+describe('checkout', () => {
+  it('adds an item to the cart', async (t) => {
+    let router = createRouter()
+    let page = await t.serve(router.fetch)
+
+    await page.goto('/')
+    await page.getByRole('button', { name: 'Add to Cart' }).click()
+    await page.getByRole('link', { name: 'Cart' }).click()
+    await page.getByRole('heading', { name: 'Shopping Cart' }).waitFor()
+
+    assert.equal(await page.locator('[data-test-cart-quantity]').innerText(), 1)
+  })
+})
+```
+
+Configure Playwright (browsers, timeouts, viewport, etc.) via `playwrightConfig` in your config file:
+
+```ts
+export default {
+  playwrightConfig: {
+    projects: [
+      { name: 'chromium', use: { browserName: 'chromium' } },
+      { name: 'firefox', use: { browserName: 'firefox' } },
+      { name: 'webkit', use: { browserName: 'webkit' } },
+    ],
+    use: {
+      navigationTimeout: 5_000,
+      actionTimeout: 5_000,
+    },
+  },
+
+  // Or, point to an existing playwright config file
+  // playwrightConfig: './playwright.config.ts'
+} satisfies RemixTestConfig
+```
+
+Set `browser.open: true` to keep the browser open after tests finish — useful for debugging failures.
+
+### Assertions
+
+`remix/test` re-exports `remix/assert`. See the [`@remix-run/assert` README](../assert/README.md) for full API documentation.
+
+```ts
+import * as assert from 'remix/assert'
+
+assert.ok(value)
+assert.equal(actual, expected)
+assert.notEqual(actual, expected)
+assert.deepEqual(actual, expected)
+assert.notDeepEqual(actual, expected)
+assert.match(string, regexp)
+assert.throws(fn)
+await assert.rejects(asyncFn)
+assert.fail('message')
+```
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tsImport } from 'tsx/esm/api';
+import { runServerTests } from "./lib/runner.js";
+import { createReporter } from "./lib/reporters/index.js";
+import { createWatcher } from "./lib/watcher.js";
+import { loadPlaywrightConfig, resolveProjects } from "./lib/playwright.js";
+import { loadConfig } from "./lib/config.js";
+const config = await loadConfig();
+let hasExited = false;
+let latestExitCode = 0;
+let watcher;
+let running = false;
+let queued = false;
+let rerunTimer;
+process.on('SIGINT', () => cleanupAndExit(latestExitCode));
+process.on('SIGTERM', () => cleanupAndExit(latestExitCode));
+try {
+    await executeRun();
+    if (config.watch) {
+        console.log('Watching for changes. Press Ctrl+C to stop.');
+    }
+}
+catch {
+    cleanupAndExit(1);
+}
+async function executeRun() {
+    if (hasExited)
+        return;
+    running = true;
+    let globalTeardown;
+    try {
+        if (config.setup) {
+            let mod = await tsImport(path.resolve(process.cwd(), config.setup), {
+                parentURL: import.meta.url,
+            });
+            let globalSetup = mod.globalSetup;
+            globalTeardown = mod.globalTeardown;
+            await globalSetup?.();
+        }
+        let { files, serverFiles, e2eFiles } = await discoverTests(config);
+        if (config.watch) {
+            watcher ??= createWatcher((file) => queueRerun(file));
+            watcher.update(files);
+        }
+        let playwrightConfig = config.playwrightConfig == null || typeof config.playwrightConfig === 'string'
+            ? await loadPlaywrightConfig(config.playwrightConfig)
+            : config.playwrightConfig;
+        let reporter = createReporter(config.reporter);
+        let startTime = performance.now();
+        let counts = {
+            passed: 0,
+            failed: 0,
+            skipped: 0,
+            todo: 0,
+        };
+        // Run server tests
+        if (serverFiles.length > 0) {
+            reporter.onSectionStart('\nRunning server tests:');
+            let serverResult = await runServerTests(serverFiles, reporter, config.concurrency, 'server');
+            counts.failed += serverResult.failed;
+            counts.passed += serverResult.passed;
+            counts.skipped += serverResult.skipped;
+            counts.todo += serverResult.todo;
+        }
+        // Run e2e tests for all browsers configured by the user
+        if (e2eFiles.length > 0) {
+            let projects = resolveProjects(playwrightConfig);
+            if (config.project) {
+                let projectNames = config.project.split(',').map((p) => p.trim());
+                projects = projects.filter((p) => p.name && projectNames.includes(p.name));
+                if (projects.length === 0) {
+                    throw new Error(`No playwright projects found with name(s) "${config.project}"`);
+                }
+            }
+            for (let project of projects) {
+                reporter.onSectionStart(`\nRunning tests for project \`${project.name}\`:`);
+                if (config.browser?.open) {
+                    if (project.playwrightUseOpts?.headless === true) {
+                        let label = project.name ? ` (project "${project.name}")` : '';
+                        console.warn(`Warning: browser.open is set but playwright headless is explicitly true${label} — ignoring browser.open`);
+                    }
+                    else {
+                        project.playwrightUseOpts = { ...project.playwrightUseOpts, headless: false };
+                    }
+                }
+                let e2eResult = e2eFiles.length > 0
+                    ? await runServerTests(e2eFiles, reporter, config.concurrency, 'e2e', {
+                        open: config.browser?.open,
+                        playwrightUseOpts: project.playwrightUseOpts,
+                        projectName: project.name,
+                    })
+                    : null;
+                counts.passed += e2eResult?.passed ?? 0;
+                counts.failed += e2eResult?.failed ?? 0;
+                counts.skipped += e2eResult?.skipped ?? 0;
+                counts.todo += e2eResult?.todo ?? 0;
+            }
+        }
+        reporter.onSummary(counts, performance.now() - startTime);
+        latestExitCode = counts.failed > 0 ? 1 : 0;
+    }
+    catch (error) {
+        console.error('Error running tests:', error);
+        latestExitCode = 1;
+    }
+    finally {
+        await globalTeardown?.();
+        running = false;
+        if (queued) {
+            queued = false;
+            queueRerun('queued change');
+        }
+        else if (!config.watch) {
+            cleanupAndExit(latestExitCode);
+        }
+    }
+}
+async function discoverTests(config) {
+    async function findFiles(pattern) {
+        let files = [];
+        let exclude = ['node_modules/**', '.git/**'];
+        for await (let file of fsp.glob(pattern, { cwd: process.cwd(), exclude })) {
+            files.push(path.resolve(process.cwd(), file));
+        }
+        return files;
+    }
+    let files = await findFiles(config.glob.test);
+    if (files.length === 0) {
+        console.log(`No test files found matching pattern: ${config.glob.test}`);
+        process.exit(1);
+    }
+    let e2eSet = new Set(await findFiles(config.glob.e2e));
+    let types = new Set(config.type.split(','));
+    let e2eFiles = types.has('e2e') ? files.filter((f) => e2eSet.has(f)) : [];
+    let serverFiles = types.has('server') ? files.filter((f) => !e2eSet.has(f)) : [];
+    let totalFiles = serverFiles.length + e2eFiles.length;
+    if (totalFiles === 0) {
+        console.log(`No test files remain after filtering for type ${config.type}`);
+        process.exit(1);
+    }
+    console.log(`Found ${totalFiles} test file(s) (${serverFiles.length} server, ${e2eFiles.length} e2e)`);
+    return {
+        files,
+        serverFiles,
+        e2eFiles,
+    };
+}
+function queueRerun(reason) {
+    if (!config.watch || hasExited)
+        return;
+    clearTimeout(rerunTimer);
+    rerunTimer = setTimeout(() => {
+        rerunTimer = undefined;
+        if (running) {
+            queued = true;
+        }
+        else {
+            console.log(`\n↻ Change detected (${reason}), re-running tests...\n`);
+            void executeRun();
+        }
+    }, 100);
+}
+function cleanupAndExit(code) {
+    if (hasExited)
+        return;
+    hasExited = true;
+    watcher?.close();
+    process.exit(code);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { RemixTestConfig } from './lib/config.ts';
+export { describe, it, suite, test, before, after, beforeEach, afterEach, beforeAll, afterAll, } from './lib/framework.ts';
+export { mock } from './lib/mock.ts';
+export type { TestContext } from './lib/context.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EACL,QAAQ,EACR,EAAE,EACF,KAAK,EACL,IAAI,EACJ,MAAM,EACN,KAAK,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,QAAQ,GACT,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { describe, it, suite, test, before, after, beforeEach, afterEach, beforeAll, afterAll, } from "./lib/framework.js";
+export { mock } from "./lib/mock.js";

package/dist/lib/config.d.ts

@@ -0,0 +1,60 @@
+import type { PlaywrightTestConfig } from 'playwright/test';
+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 declare function loadConfig(): Promise<ResolvedRemixTestConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAgF3D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;KACf,CAAA;IACD;;;;OAIG;IACH,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;IACD,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAA;IAChD,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE;QACP,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,IAAI,CAAC,EAAE,OAAO,CAAA;KACf,CAAA;IACD,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;IACD,gBAAgB,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAA;IAC3D,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,UAAU,qCAU/B"}