@remix-run/test 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,15 @@
 # `test`
 
-A test framework for Remix applications
+A test framework for JavaScript and TypeScript projects.
 
 ## Features
 
 - `describe`/`it` test structure with `before`/`after`/`beforeEach`/`afterEach` hooks
 - Server-side unit testing
 - Playwright E2E testing via `t.serve`
+- In-browser component testing (pair with `render` from `remix/ui/test`)
 - Mock functions and method spies via `t.mock.fn` / `t.mock.method`
+- Unified code coverage reporting across unit and E2E tests
 - Watch mode
 - Config file support (`remix-test.config.ts`)
 
@@ -36,17 +38,24 @@ describe('My Test Suite', () => {
 Run tests with the CLI:
 
 ```sh
-remix-test
+remix test
 ```
 
-By default, `remix-test` discovers all files matching `**/*.test.{ts,tsx}`. Pass a glob as the first positional argument to override:
+By default, `remix test` discovers all files matching `**/*.test{,.e2e}.{ts,tsx}`. Pass a glob as the first positional argument to override:
 
 ```sh
-remix-test "src/**/*.test.ts"
+remix test "src/**/*.test.ts"
 ```
 
 Or, you may control via the `glob.test` config field/CLI arg.
 
+If you install `@remix-run/test` directly instead of the umbrella `remix` package, the same runner is available as `remix-test`:
+
+```sh
+npm i @remix-run/test
+remix-test
+```
+
 ### Config File
 
 Create a `remix-test.config.ts` (or `.js`) file at the root of your project (shown with default values):
@@ -67,10 +76,28 @@ export default {
   // Max number of concurrent test workers (default `os.availableParallelism()`)
   concurrency: 2,
 
+  // Code coverage options
+  coverage: {
+    // Enable coverage reporting
+    enabled: true,
+    // Output directory (default: ".coverage")
+    dir: '.coverage',
+    // Glob patterns to include/exclude
+    include: ['src/**'],
+    exclude: ['src/**/*.test.ts'],
+    // Minimum thresholds (%)
+    statements: 80,
+    lines: 80,
+    branches: 80,
+    functions: 80,
+  },
+
   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}")
+    // Glob pattern identifying all test files (default: "**/*.test{,.browser,.e2e}.{ts,tsx}")
+    test: '**/*.test{,.browser,.e2e}.ts',
+    // Glob pattern identifying browser test files (default: "**/*.test.browser.{ts,tsx}")
+    browser: '**/*.test.browser.ts',
+    // Glob pattern identifying E2E test files (default: "**/*.test.e2e.{ts,tsx}")
     e2e: '**/*.test.e2e.ts',
   },
 
@@ -96,8 +123,8 @@ export default {
   // 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',
+  // Comma-separated list of test types to run ("server", "browser", "e2e")
+  type: 'server,browser,e2e',
 
   // Watch for file changes and re-run
   watch: false,
@@ -109,7 +136,7 @@ export default {
 You can point to a different config file location with the `--config` flag:
 
 ```sh
-remix-test --config ./tests/config.ts
+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:
@@ -119,7 +146,16 @@ You may also specify any config field as a CLI flag which will take precedence o
 | `--browser.echo`            |       |
 | `--browser.open`            |       |
 | `--concurrency <n>`         | `-c`  |
+| `--coverage`                |       |
+| `--coverage.dir <path>`     |       |
+| `--coverage.include`        |       |
+| `--coverage.exclude`        |       |
+| `--coverage.statements`     |       |
+| `--coverage.lines`          |       |
+| `--coverage.branches`       |       |
+| `--coverage.functions`      |       |
 | `--glob.test`               |       |
+| `--glob.browser`            |       |
 | `--glob.e2e`                |       |
 | `--playwrightConfig <path>` |       |
 | `--project <name>`          | `-p`  |
@@ -172,11 +208,30 @@ suite('My Test Suite', () => {
 })
 ```
 
+### Programmatic runner
+
+`@remix-run/test/cli` exports `runRemixTest()` for tools that want to run the test runner without
+exiting the current process:
+
+```ts
+import { runRemixTest } from '@remix-run/test/cli'
+
+let exitCode = await runRemixTest({
+  argv: ['--type', 'server'],
+  cwd: process.cwd(),
+})
+```
+
+`runRemixTest()` returns the runner exit code. The `remix test` and `remix-test` bin wrappers call
+`process.exit()` with that code when the run finishes so open workers, browsers, or project handles
+cannot keep the CLI alive.
+
 ### Test Context
 
 Each test callback receives a `TestContext` (`t`) as its first argument with helpful test utilities.
 
 ```ts
+// from 'remix/test'
 interface TestContext {
   // Register a cleanup function to run after the test completes
   after(fn: () => void): void
@@ -194,8 +249,11 @@ interface TestContext {
     ): MockFunction
   }
 
-  // E2E only: start a server with the given request handler, returns a Playwright Page
-  serve(handler: (req: Request) => Promise<Response>): Promise<Page>
+  // Replace global timer functions with controllable fakes
+  useFakeTimers(): FakeTimers
+
+  // E2E only: connect a running test server to a Playwright Page
+  serve(server: { baseUrl: string; close(): Promise<void> }): Promise<Page>
 }
 ```
 
@@ -230,14 +288,40 @@ it('cleanup', (t) => {
 })
 ```
 
+#### Fake Timers
+
+`t.useFakeTimers()` replaces the global timer functions (`setTimeout`, `setInterval`, etc.) with controllable fakes that are automatically restored after the test. It works in any test environment — server unit tests, browser tests, or E2E setup code.
+
+```ts
+it('debounces a callback', (t) => {
+  let timers = t.useFakeTimers()
+  let calls = 0
+  let debounced = debounce(() => calls++, 300)
+
+  debounced()
+  timers.advance(299)
+  assert.equal(calls, 0)
+  timers.advance(1)
+  assert.equal(calls, 1)
+})
+```
+
+| Method        | Description                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| `advance(ms)` | Advance the clock by `ms` milliseconds, firing any elapsed timers           |
+| `restore()`   | Restore the original timer functions (called automatically after each test) |
+
 #### E2E
 
-In E2E test files, `t.serve()` starts an HTTP server and returns a Playwright `Page`. See [E2E Testing](#e2e-testing) for details.
+In E2E test files, `t.serve()` connects a running test server to a Playwright `Page`. See [E2E Testing](#e2e-testing) for details.
 
 ```ts
+import { createTestServer } from 'remix/node-fetch-server/test'
+
 it('navigates to home', async (t) => {
   let router = createRouter()
-  let page = await t.serve(router.fetch)
+  let server = await createTestServer(router.fetch)
+  let page = await t.serve(server)
   await page.goto('/')
 })
 ```
@@ -254,21 +338,60 @@ let spy = mock.method(console, 'log')
 spy.mock.restore?.()
 ```
 
+### Browser Testing
+
+Browser tests run components in an actual browser environment via Playwright and are discovered by the `**/*.test.browser.{ts,tsx}` glob pattern (configurable via `glob.browser`). They use the same `describe`/`it` API as unit tests. Each in-browser test suite runs in an isolated `iframe` so it has access to its own `document` instance.
+
+#### `render()`
+
+`render`, exported from `remix/ui/test`, mounts a component into the DOM and returns a `RenderResult`:
+
+```ts
+import * as assert from 'remix/assert'
+import { describe, it } from 'remix/test'
+import { render } from 'remix/ui/test'
+import { Counter } from './counter.tsx'
+
+describe('Counter', () => {
+  it('increments on click', async (t) => {
+    let { $, act, cleanup } = render(<Counter />)
+    t.after(cleanup)
+
+    assert.equal($('[data-count]')?.textContent, '0')
+    await act(() => $('[data-action="increment"]')?.click())
+    assert.equal($('[data-count]')?.textContent, '1')
+  })
+})
+```
+
+`RenderResult` provides:
+
+| Property/Method | Description                                                             |
+| --------------- | ----------------------------------------------------------------------- |
+| `container`     | The `HTMLElement` the component is mounted into                         |
+| `root`          | The Remix `VirtualRoot` the component is rendered in                    |
+| `$(selector)`   | Alias for `container.querySelector()`                                   |
+| `$$(selector)`  | Alias for `container.querySelectorAll()`                                |
+| `act(fn)`       | Runs `fn` and flushes pending component updates                         |
+| `cleanup()`     | Unmounts and removes the container (pass to `t.after` for auto-cleanup) |
+
 ### 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.
+End-to-end (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.
+E2E tests receive `t.serve()` on the test context, which accepts a running test server and returns a Playwright [`Page`](https://playwright.dev/docs/api/class-page) whose `baseURL` points at that server. The server and page are automatically closed after each test.
 
 ```ts
 import * as assert from 'remix/assert'
+import { createTestServer } from 'remix/node-fetch-server/test'
 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)
+    let server = await createTestServer(router.fetch)
+    let page = await t.serve(server)
 
     await page.goto('/')
     await page.getByRole('button', { name: 'Add to Cart' }).click()
@@ -303,24 +426,6 @@ export default {
 
 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/app/client/entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entry.d.ts.map

package/dist/app/client/entry.d.ts.map

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

package/dist/app/client/entry.js

@@ -0,0 +1,324 @@
+import { normalizeLine } from "../../lib/normalize.js";
+const STYLES = `
+.rt-container {
+  font-family: monospace;
+  padding: 16px;
+  max-width: 900px;
+}
+.rt-summary {
+  margin-bottom: 16px;
+  line-height: 1.6;
+}
+.rt-summary-row {
+  display: block;
+}
+.rt-info {
+  color: #0ea5e9;
+}
+.rt-indent {
+  margin-left: 16px;
+  margin-top: 4px;
+}
+.rt-suite-details {
+  margin-bottom: 8px;
+}
+.rt-suite-summary {
+  cursor: pointer;
+  padding: 2px 0;
+  user-select: none;
+}
+.rt-suite-icon {
+  margin-left: 6px;
+}
+.rt-test-item {
+  padding: 3px 18px;
+}
+.rt-test-duration {
+  color: #999;
+  font-size: 0.85em;
+}
+.rt-error-pre {
+  margin: 4px 0 4px 16px;
+  padding: 8px 12px;
+  font-size: 12px;
+  color: #dc2626;
+  background: #fff5f5;
+  border-left: 3px solid #dc2626;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.rt-error-stack {
+  color: #999;
+  margin-top: 6px;
+}
+.rt-button {
+  margin-top: 8px;
+  padding: 6px 12px;
+  cursor: pointer;
+}
+.rt-stack-link {
+  color: inherit;
+  text-decoration: underline;
+  text-decoration-color: #aaa;
+}
+.rt-passed {
+  color: #16a34a;
+}
+.rt-failed {
+  color: #dc2626;
+}
+.rt-muted {
+  color: #666;
+}
+.rt-todo {
+  color: #a16207;
+}
+`;
+const styleEl = document.createElement('style');
+styleEl.textContent = STYLES;
+document.head.appendChild(styleEl);
+const setupEl = document.getElementById('test-setup');
+if (!setupEl?.textContent) {
+    throw new Error('Test runner: missing #test-setup payload');
+}
+const setup = JSON.parse(setupEl.textContent);
+const root = document.getElementById('test-root');
+if (!root) {
+    throw new Error('Test runner: missing #test-root mount point');
+}
+mountTests(root, setup);
+function mountTests(host, setup) {
+    let startTime = performance.now();
+    let totals = { passed: 0, failed: 0, skipped: 0, todo: 0 };
+    let container = el('div', { id: 'test-status', className: 'rt-container' });
+    host.appendChild(container);
+    let summary = el('div', { className: 'rt-summary' });
+    container.appendChild(summary);
+    let testsRow = summaryRow();
+    let passRow = summaryRow();
+    let failRow = summaryRow();
+    let skippedRow = summaryRow();
+    let todoRow = summaryRow();
+    let durationRow = summaryRow();
+    summary.append(testsRow.el, passRow.el, failRow.el);
+    let suitesContainer = el('div');
+    container.appendChild(suitesContainer);
+    function renderSummary(done) {
+        let total = totals.passed + totals.failed + totals.skipped + totals.todo;
+        testsRow.text(`tests ${total}`);
+        passRow.text(`pass ${totals.passed}`);
+        failRow.text(`fail ${totals.failed}`);
+        if (totals.skipped > 0) {
+            if (!skippedRow.el.parentNode)
+                summary.appendChild(skippedRow.el);
+            skippedRow.text(`skipped ${totals.skipped}`);
+        }
+        if (totals.todo > 0) {
+            if (!todoRow.el.parentNode)
+                summary.appendChild(todoRow.el);
+            todoRow.text(`todo ${totals.todo}`);
+        }
+        if (done) {
+            if (!durationRow.el.parentNode)
+                summary.appendChild(durationRow.el);
+            durationRow.text(`duration_ms ${(performance.now() - startTime).toFixed(5)}`);
+        }
+    }
+    function appendFileSuites(fileResults) {
+        let suiteMap = new Map();
+        for (let test of fileResults.tests) {
+            let suite = test.suiteName || 'Tests';
+            if (!suiteMap.has(suite))
+                suiteMap.set(suite, []);
+            suiteMap.get(suite).push(test);
+        }
+        for (let [suiteName, tests] of suiteMap) {
+            suitesContainer.appendChild(buildSuite(suiteName, tests, setup.baseDir));
+        }
+    }
+    function appendRerunButton() {
+        let button = el('button', { className: 'rt-button', textContent: 'Re-run' });
+        button.type = 'button';
+        button.addEventListener('click', () => window.location.reload());
+        container.appendChild(button);
+    }
+    renderSummary(false);
+    void (async () => {
+        for (let testFile of setup.testPaths) {
+            let fileResults = await runInIframe(testFile);
+            await fetch('/file-results', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(fileResults),
+            });
+            totals.passed += fileResults.passed;
+            totals.failed += fileResults.failed;
+            totals.skipped += fileResults.skipped;
+            totals.todo += fileResults.todo;
+            appendFileSuites(fileResults);
+            renderSummary(false);
+        }
+        renderSummary(true);
+        appendRerunButton();
+        window.__testsDone = true;
+    })();
+}
+function runInIframe(testFile) {
+    return new Promise((resolve) => {
+        let iframe = document.createElement('iframe');
+        iframe.src = `/iframe?file=${encodeURIComponent(testFile)}`;
+        document.body.appendChild(iframe);
+        function onMessage(event) {
+            if (event.source !== iframe.contentWindow)
+                return;
+            window.removeEventListener('message', onMessage);
+            // Hide instead of remove so when coverage is enabled the iframe remains attached
+            // so V8 retains its scripts and Playwright can collect coverage at run end.
+            iframe.style.display = 'none';
+            if (event.data.type === 'test-results') {
+                let { passed, failed, skipped, todo, tests } = event.data.results;
+                resolve({
+                    passed,
+                    failed,
+                    skipped,
+                    todo,
+                    tests: tests.map((t) => ({ ...t, filePath: testFile })),
+                });
+            }
+            else {
+                let { message, stack } = event.data.error;
+                resolve({
+                    passed: 0,
+                    failed: 1,
+                    skipped: 0,
+                    todo: 0,
+                    tests: [
+                        {
+                            name: '',
+                            suiteName: testFile,
+                            filePath: testFile,
+                            status: 'failed',
+                            error: { message, stack },
+                            duration: 0,
+                        },
+                    ],
+                });
+            }
+        }
+        window.addEventListener('message', onMessage);
+    });
+}
+function buildSuite(suiteName, tests, baseDir) {
+    let suiteFailed = tests.some((t) => t.status === 'failed');
+    let suiteAllSkipped = tests.every((t) => t.status === 'skipped');
+    let suiteAllTodo = tests.every((t) => t.status === 'todo');
+    let stateClass = suiteFailed
+        ? 'rt-failed'
+        : suiteAllSkipped
+            ? 'rt-muted'
+            : suiteAllTodo
+                ? 'rt-todo'
+                : 'rt-passed';
+    let icon = suiteFailed ? '✗' : suiteAllSkipped ? '↓' : suiteAllTodo ? '…' : '✓';
+    let suffix = suiteAllSkipped ? ' # skipped' : suiteAllTodo ? ' # todo' : '';
+    let details = el('details', { className: 'rt-suite-details' });
+    if (suiteFailed)
+        details.open = true;
+    let summary = el('summary', { className: `rt-suite-summary ${stateClass}` });
+    summary.appendChild(el('span', { className: 'rt-suite-icon', textContent: `${icon} ${suiteName}${suffix}` }));
+    details.appendChild(summary);
+    let body = el('div', { className: 'rt-indent' });
+    for (let test of tests) {
+        let item = buildTestItem(test, baseDir);
+        if (item)
+            body.appendChild(el('div', { className: 'rt-test-item' }, item));
+    }
+    details.appendChild(body);
+    return details;
+}
+function buildTestItem(test, baseDir) {
+    if (test.status === 'passed') {
+        let row = el('div', { className: 'rt-passed' });
+        row.append(`✓ ${test.name} `);
+        row.appendChild(el('span', {
+            className: 'rt-test-duration',
+            textContent: `(${test.duration.toFixed(2)}ms)`,
+        }));
+        return row;
+    }
+    if (test.status === 'failed') {
+        let row = el('div', { className: 'rt-failed' });
+        row.append(`✗ ${test.name} `);
+        row.appendChild(el('span', {
+            className: 'rt-test-duration',
+            textContent: `(${test.duration.toFixed(2)}ms)`,
+        }));
+        if (test.error) {
+            let pre = el('pre', { className: 'rt-error-pre' });
+            pre.append(test.error.message);
+            if (test.error.stack) {
+                let stackDiv = el('div', { className: 'rt-error-stack' });
+                stackDiv.appendChild(buildStack(test.error.stack, baseDir));
+                pre.appendChild(stackDiv);
+            }
+            row.appendChild(pre);
+        }
+        return row;
+    }
+    if (test.status === 'skipped' && test.name) {
+        return el('div', { className: 'rt-muted', textContent: `↓ ${test.name} # skipped` });
+    }
+    if (test.status === 'todo' && test.name) {
+        return el('div', { className: 'rt-todo', textContent: `… ${test.name} # todo` });
+    }
+    return null;
+}
+function buildStack(stack, baseDir) {
+    let frameLocRe = /([^():\s][^():]*\.[jt]sx?):(\d+):(\d+)/;
+    let frag = document.createDocumentFragment();
+    for (let raw of stack.split('\n')) {
+        let isTestModule = raw.includes('/@test/');
+        let line = normalizeLine(raw);
+        let match = isTestModule ? frameLocRe.exec(line) : null;
+        let div = document.createElement('div');
+        if (match) {
+            let [full, file, row, col] = match;
+            let abs = `${baseDir}/${file}`;
+            let href = `vscode://file/${abs}:${row}:${col}`;
+            div.append(line.slice(0, match.index));
+            let a = el('a', { className: 'rt-stack-link', textContent: full });
+            a.href = href;
+            div.appendChild(a);
+            div.append(line.slice(match.index + full.length));
+        }
+        else {
+            div.textContent = line;
+        }
+        frag.appendChild(div);
+    }
+    return frag;
+}
+function summaryRow() {
+    let row = el('span', { className: 'rt-summary-row' });
+    let icon = el('span', { className: 'rt-info', textContent: 'ℹ' });
+    let textNode = document.createTextNode('');
+    row.append(icon, ' ', textNode);
+    return {
+        el: row,
+        text(s) {
+            textNode.data = ' ' + s;
+        },
+    };
+}
+function el(tag, props, ...children) {
+    let node = document.createElement(tag);
+    if (props?.id)
+        node.id = props.id;
+    if (props?.className)
+        node.className = props.className;
+    if (props?.textContent != null)
+        node.textContent = props.textContent;
+    if (children.length)
+        node.append(...children);
+    return node;
+}

package/dist/app/client/iframe.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=iframe.d.ts.map

package/dist/app/client/iframe.d.ts.map

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

package/dist/app/client/iframe.js

@@ -0,0 +1,22 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { runTests } from "../../lib/executor.js";
+const params = new URLSearchParams(location.search);
+const testFile = params.get('file');
+try {
+    await import(__rewriteRelativeImportExtension(testFile));
+    let results = await runTests();
+    window.parent.postMessage({ type: 'test-results', results }, '*');
+}
+catch (error) {
+    window.parent.postMessage({
+        type: 'test-error',
+        error: { message: error?.message ?? String(error), stack: error?.stack },
+    }, '*');
+}

package/dist/app/server.d.ts

@@ -0,0 +1,6 @@
+import * as http from 'node:http';
+export declare function startServer(browserFiles: string[]): Promise<{
+    server: http.Server;
+    port: number;
+}>;
+//# sourceMappingURL=server.d.ts.map

package/dist/app/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/app/server.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAQjC,wBAAsB,WAAW,CAC/B,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAkChD"}