proby 0.13.0 → 0.13.1

package/README.md

@@ -5,8 +5,10 @@ Test runner for JavaScript runtimes.
 ## What is proby?
 
 A cross-runtime test runner that automatically discovers and runs test files.
-Works with both single repositories and monorepos. Uses `@rcompat/test` for
-writing tests. Works consistently across Node, Deno, and Bun.
+Works with both single repositories and monorepos. Supports TypeScript source
+execution in monorepos without a build step when your packages expose `source`
+entries in `package.json`. Uses `@rcompat/test` for writing tests. Works
+consistently across Node, Deno, and Bun.
 
 ## Installation
 
@@ -43,45 +45,213 @@ npx proby
 ```
 
 Run a single file:
+
 ```bash
 npx proby math.spec.ts
 ```
 
 Run a single group within a file:
+
 ```bash
 npx proby math.spec.ts addition
 ```
 
-### Grouping tests
+## How proby resolves source files
 
-Use `test.group` in your spec files to cluster related cases. Groups can then
-be targeted individually when running proby:
-```js
-// src/math.spec.ts
-import test from "@rcompat/test";
+Proby relaunches itself with runtime conditions before running tests. By
+default it uses the `source` condition, which lets runtimes resolve package
+`imports` and `exports` to your TypeScript source files instead of built
+JavaScript.
 
-test.group("addition", () => {
-  test.case("integers", assert => {
-    assert(1 + 1).equals(2);
-  });
-});
+This is especially useful in monorepos where packages depend on each other and
+you want to run tests against source directly.
 
-test.group("multiplication", () => {
-  test.case("integers", assert => {
-    assert(2 * 3).equals(6);
-  });
+To use this pattern, expose `source` entries in your packages.
+
+Example:
+
+```json
+{
+  "imports": {
+    "#*": {
+      "source": "./src/*.ts",
+      "default": "./lib/*.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./lib/index.js"
+    }
+  }
+}
+```
+
+With this setup, proby can run against your TypeScript source without requiring
+an upfront build step.
+
+## Configuration
+
+Create `proby.config.ts` or `proby.config.js` in your project root.
+
+```ts
+import config from "proby/config";
+
+export default config({
+  monorepo: true,
+  packages: "packages",
+  include: ["src"],
+  conditions: ["source"],
 });
 ```
-```bash
-npx proby math.spec.ts addition  # runs only the addition group
+
+### Config options
+
+#### `monorepo`
+
+```ts
+boolean
 ```
 
-### Grouping tests
+Whether proby should scan package directories inside a monorepo.
+
+Default:
+
+```ts
+false
+```
+
+#### `packages`
+
+```ts
+string
+```
+
+Directory containing package folders when `monorepo` is enabled.
+
+Default:
+
+```ts
+"packages"
+```
+
+#### `include`
+
+```ts
+string[]
+```
+
+Directories to scan for spec files.
+
+Default:
+
+```ts
+["src"]
+```
+
+#### `conditions`
+
+```ts
+string[]
+```
+
+Runtime conditions used when proby relaunches itself.
+
+Default:
+
+```ts
+["source"]
+```
+
+## Project structure
+
+Proby automatically detects your project structure.
+
+### Single repository
+
+```text
+my-project/
+├── src/
+│   ├── utils.ts
+│   ├── utils.spec.ts
+│   ├── math.ts
+│   └── math.spec.ts
+└── package.json
+```
+
+### Monorepo
+
+```text
+my-monorepo/
+├── packages/
+│   ├── core/
+│   │   └── src/
+│   │       ├── index.ts
+│   │       └── index.spec.ts
+│   └── utils/
+│       └── src/
+│           ├── helpers.ts
+│           └── helpers.spec.ts
+└── package.json
+```
+
+## Test file conventions
+
+- Files must end with `.spec.ts` or `.spec.js`
+- Files must be in one of the configured include directories
+- Use `@rcompat/test` to write tests
+- Use `test.group` to organize cases into named groups targetable by proby
+
+## Static mock files
+
+Proby supports preloading sibling mock files before a spec file is evaluated.
+This allows module mocks to be registered before the spec's static imports are
+read.
+
+Pair files by matching the spec extension exactly:
+
+- `math.spec.ts` pairs with `math.mock.ts`
+- `math.spec.js` pairs with `math.mock.js`
+
+If a sibling mock file exists, proby loads it before the spec file.
+
+Example:
+
+```ts
+// math.ts
+export function add(a: number, b: number) {
+  return a + b;
+}
+```
+
+```ts
+// math.mock.ts
+import test from "@rcompat/test";
+
+test.mock("./math.ts", () => ({
+  add: (a: number, b: number) => 99,
+}));
+```
+
+```ts
+// math.spec.ts
+import test from "@rcompat/test";
+import { add } from "./math.ts";
+
+test.case("uses the preloaded mock", assert => {
+  assert(add(1, 2)).equals(99);
+});
+```
+
+Static mocks are file-scoped. A mock loaded for one spec file does not leak
+into later spec files.
+
+## Grouping tests
 
 Use `test.group` in your spec files to cluster related cases. Groups can then
-be targeted individually when running proby:
+be targeted individually when running proby.
+
 ```js
-// src/math.spec.ts
 import test from "@rcompat/test";
 
 test.group("addition", () => {
@@ -96,17 +266,16 @@ test.group("multiplication", () => {
   });
 });
 ```
+
 ```bash
-npx proby math.spec.ts addition  # runs only the addition group
+npx proby math.spec.ts addition
 ```
 
-### Writing tests
+## Writing tests
 
-Create test files with `.spec.ts` or `.spec.js` extension in your `src`
-directory:
+Create test files with `.spec.ts` or `.spec.js`:
 
 ```js
-// src/math.spec.ts
 import test from "@rcompat/test";
 
 test.case("addition", assert => {
@@ -120,50 +289,21 @@ test.case("multiplication", assert => {
 });
 ```
 
-### Test output
+## Test output
 
 Proby displays colored output:
+
 - Green `o` for passing tests
 - Red `x` for failing tests
 
-```
+```text
 oooooxoo
 src/math.spec.ts division
   expected  5
   actual    4
 ```
 
-### Project structure
-
-Proby automatically detects your project structure:
-
-**Single repository:**
-```
-my-project/
-├── src/
-│   ├── utils.ts
-│   ├── utils.spec.ts    # ← Test file
-│   ├── math.ts
-│   └── math.spec.ts     # ← Test file
-└── package.json
-```
-
-**Monorepo:**
-```
-my-monorepo/
-├── packages/
-│   ├── core/
-│   │   └── src/
-│   │       ├── index.ts
-│   │       └── index.spec.ts  # ← Test file
-│   └── utils/
-│       └── src/
-│           ├── helpers.ts
-│           └── helpers.spec.ts  # ← Test file
-└── package.json
-```
-
-### npm scripts
+## npm scripts
 
 Add proby to your `package.json`:
 
@@ -181,13 +321,6 @@ Then run:
 npm test
 ```
 
-## Test file conventions
-
-- Files must end with `.spec.ts` or `.spec.js`
-- Files must be in the `src` directory (or `packages/*/src` for monorepos)
-- Use `@rcompat/test` to write tests
-- Use `test.group` to organize cases into named groups targetable by proby
-
 ## Examples
 
 ### Basic assertions
@@ -196,17 +329,10 @@ npm test
 import test from "@rcompat/test";
 
 test.case("basic assertions", assert => {
-  // equality
   assert(value).equals(expected);
-
-  // truthiness
   assert(condition).true();
   assert(condition).false();
-
-  // type checking
   assert(value).type<string>();
-
-  // throws
   assert(() => throwingFunction()).throws();
   assert(() => safeFunction()).tries();
 });
@@ -227,7 +353,7 @@ test.case("async operations", async assert => {
 
 ```js
 // src/calculator.ts
-export function add(a: number, b: number) {
+export function add(a, b) {
   return a + b;
 }
 
@@ -245,13 +371,11 @@ test.case("add function", assert => {
 ## Cross-Runtime Compatibility
 
 | Runtime | Supported |
-|---------|-----------|
+| ------- | --------- |
 | Node.js | ✓         |
 | Deno    | ✓         |
 | Bun     | ✓         |
 
-No configuration required — just run `npx proby`.
-
 ## License
 
 MIT

package/lib/bin.js

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
-import Schema from "#Schema";
+import p from "pema";
 import env from "@rcompat/env";
 import fs from "@rcompat/fs";
 import io from "@rcompat/io";
 import is from "@rcompat/is";
 import runtime from "@rcompat/runtime";
+const Schema = p({
+    monorepo: p.boolean.default(false),
+    packages: p.string.default("packages"),
+    include: p.array(p.string).default(["src"]),
+    conditions: p.array(p.string).default(["source"]),
+});
 const root = await fs.project.root();
 const ts_config_file = root.join("proby.config.ts");
 const js_config_file = root.join("proby.config.js");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proby",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Standard library test runner",
   "bugs": "https://github.com/rcompat/rcompat/issues",
   "license": "MIT",
@@ -20,8 +20,8 @@
     "@rcompat/assert": "^0.8.0",
     "@rcompat/cli": "^0.18.0",
     "@rcompat/env": "^0.17.0",
-    "@rcompat/io": "^0.5.0",
     "@rcompat/fs": "^0.28.0",
+    "@rcompat/io": "^0.5.0",
     "@rcompat/is": "^0.6.0",
     "@rcompat/runtime": "^0.11.0"
   },