@isentinel/jest-roblox 0.0.4 → 0.0.6

package/README.md

@@ -0,0 +1,299 @@
+# jest-roblox-cli
+
+Run your TypeScript and Luau tests inside Roblox, then see the results in your
+terminal.
+
+jest-roblox-cli takes your test files, builds a Roblox place, runs the tests
+in Roblox, and brings the results back to you. It works with both roblox-ts
+(TypeScript) and pure Luau projects. For TypeScript projects, it maps errors
+back to your original source.
+
+## Why use this?
+
+Roblox code needs Roblox to run. You can't test it with normal tools because
+the Roblox API only exists inside the engine. This tool runs your tests in a
+real Roblox session, then reports results in your terminal.
+
+- Works with roblox-ts and pure Luau projects
+- For TypeScript projects, maps Luau errors back to your `.ts` files
+- Collects code coverage so you know which lines your tests touch
+- Supports two backends: Roblox Open Cloud (remote) and Roblox Studio (local)
+
+## Install
+
+```bash
+npm install @isentinel/jest-roblox
+```
+
+## Quick start
+
+Create a config file in your project root.
+
+**roblox-ts project** (`jest.config.ts`):
+
+```typescript
+import { defineConfig } from "@isentinel/jest-roblox";
+
+export default defineConfig({
+	placeFile: "./game.rbxl",
+	projects: ["ReplicatedStorage/shared"],
+});
+```
+
+**Luau project** (`jest.config.json`):
+
+```json
+{
+	"luauRoots": ["./src"],
+	"placeFile": "./game.rbxl",
+	"projects": ["ReplicatedStorage/shared"]
+}
+```
+
+Then run your tests:
+
+```bash
+jest-roblox
+```
+
+## Usage
+
+```bash
+# Run all tests
+jest-roblox
+
+# Run one file (TypeScript or Luau)
+jest-roblox src/player.spec.ts
+jest-roblox src/player.spec.luau
+
+# Filter by test name
+jest-roblox -t "should spawn"
+
+# Filter by file path
+jest-roblox --testPathPattern player
+
+# Use a specific backend
+jest-roblox --backend studio
+jest-roblox --backend open-cloud
+
+# Collect coverage
+jest-roblox --coverage
+
+# Output JSON results
+jest-roblox --json --outputFile results.json
+
+# Short output for AI tools
+jest-roblox --compact
+```
+
+## Configuration
+
+You can put your config in any of these formats (c12 discovers them
+automatically):
+
+- `jest.config.ts` / `jest.config.js` / `jest.config.mjs` / `jest.config.cjs`
+- `jest.config.json` / `jest.config.yaml` / `jest.config.toml`
+
+CLI flags always win over config file values. Config file values always win over
+built-in defaults.
+
+### Config fields
+
+| Field | What it does | Default |
+|---|---|---|
+| `projects` | Where to look for tests in the DataModel | **required** |
+| `backend` | `"auto"`, `"open-cloud"`, or `"studio"` | `"auto"` |
+| `placeFile` | Path to your `.rbxl` file | `"./game.rbxl"` |
+| `timeout` | Max time for tests to run (ms) | `300000` (5 min) |
+| `sourceMap` | Map Luau errors back to TypeScript (roblox-ts only) | `true` |
+| `port` | WebSocket port for Studio backend | `3001` |
+| `testMatch` | Glob patterns that find test files | `**/*.spec.ts`, `**/*.test.ts`, etc. |
+| `testPathIgnorePatterns` | Patterns to skip | `/node_modules/`, `/dist/` |
+| `rojoProject` | Path to your Rojo project file | auto |
+| `jestPath` | Where Jest lives in the DataModel | auto |
+| `setupFiles` | Scripts to run before the test environment loads | — |
+| `setupFilesAfterEnv` | Scripts to run after the test environment loads | — |
+
+### Coverage fields
+
+| Field | What it does | Default |
+|---|---|---|
+| `collectCoverage` | Turn on coverage | `false` |
+| `coverageDirectory` | Where to write coverage reports | `"coverage"` |
+| `coverageReporters` | Which report formats to use | `["text", "lcov"]` |
+| `coverageThreshold` | Minimum coverage to pass | — |
+| `coveragePathIgnorePatterns` | Files to leave out of coverage | test files, node_modules |
+| `collectCoverageFrom` | Globs for files to include in coverage | — |
+| `luauRoots` | Where Luau files live (auto from tsconfig `outDir` for roblox-ts, or set by hand for pure Luau) | auto |
+
+### Full example (roblox-ts)
+
+```typescript
+import { defineConfig } from "@isentinel/jest-roblox";
+
+export default defineConfig({
+	backend: "open-cloud",
+	collectCoverage: true,
+	coverageThreshold: {
+		branches: 70,
+		functions: 80,
+		statements: 80,
+	},
+	jestPath: "ReplicatedStorage/Packages/Jest",
+	placeFile: "./game.rbxl",
+	projects: ["ReplicatedStorage/client", "ServerScriptService/server"],
+	timeout: 60000,
+});
+```
+
+### Full example (Luau)
+
+```json
+{
+	"backend": "open-cloud",
+	"collectCoverage": true,
+	"coverageThreshold": {
+		"branches": 70,
+		"functions": 80,
+		"statements": 80
+	},
+	"jestPath": "ReplicatedStorage/Packages/Jest",
+	"luauRoots": ["./src"],
+	"placeFile": "./game.rbxl",
+	"projects": ["ReplicatedStorage/client", "ServerScriptService/server"],
+	"timeout": 60000
+}
+```
+
+## Backends
+
+jest-roblox-cli can run tests two ways:
+
+### Open Cloud (remote)
+
+Uploads your place file to Roblox, runs the tests there, and polls for results.
+
+You need these environment variables:
+
+| Variable | What it is |
+|---|---|
+| `ROBLOX_OPEN_CLOUD_API_KEY` | Your Open Cloud API key |
+| `ROBLOX_UNIVERSE_ID` | The universe to run tests in |
+| `ROBLOX_PLACE_ID` | The place to run tests in |
+
+### Studio (local)
+
+Connects to Roblox Studio on your machine through a WebSocket plugin. This is
+faster because there is no upload step, but requires Roblox Studio to be open
+and running the plugin.
+
+> [!TIP]
+> In auto mode, the CLI tries Studio first. If Studio is not running, it falls back to Open Cloud.
+
+## CLI flags
+
+| Flag | What it does |
+|---|---|
+| `--backend <type>` | Choose `auto`, `open-cloud`, or `studio` |
+| `--port <n>` | WebSocket port for Studio |
+| `--config <path>` | Path to config file |
+| `--testPathPattern <regex>` | Filter test files by path |
+| `-t, --testNamePattern <regex>` | Filter tests by name |
+| `--json` | Output results as JSON |
+| `--compact` | Short output for AI tools |
+| `--outputFile <path>` | Write results to a file |
+| `--coverage` | Collect coverage |
+| `--coverageDirectory <path>` | Where to put coverage reports |
+| `--coverageReporters <r...>` | Which report formats to use |
+| `--luauRoots <path...>` | Where compiled Luau files live |
+| `-u, --updateSnapshot` | Update snapshot files |
+| `--sourceMap` | Map Luau errors to TypeScript (roblox-ts only) |
+| `--rojoProject <path>` | Path to Rojo project file |
+| `--verbose` | Show each test result |
+| `--silent` | Hide all output |
+| `--no-color` | Turn off colors |
+| `--no-cache` | Force a fresh place file upload |
+| `--pollInterval <ms>` | How often to check for results (Open Cloud) |
+| `--projects <path...>` | DataModel paths that hold tests |
+| `--setupFiles <path...>` | Scripts to run before env |
+| `--setupFilesAfterEnv <path...>` | Scripts to run after env |
+| `--typecheck` | Run type tests too |
+| `--typecheckOnly` | Run only type tests |
+| `--typecheckTsconfig <path>` | tsconfig for type tests |
+
+## How it works
+
+1. Scans your project for files that match `testMatch` patterns
+2. Uses Rojo to build a `.rbxl` file with your code
+3. Sends the place to Roblox via Open Cloud or Studio over WebSocket
+4. Reads Jest JSON output from the Roblox session
+5. For roblox-ts projects, turns Luau line numbers into TypeScript line numbers
+   using source maps
+6. Prints pass/fail results in your terminal
+
+> [!NOTE]
+> For coverage, there are extra steps. The tool copies your Luau files, adds
+> tracking code to each line, and builds a special place file. After the tests
+> run, it maps the tracking data back to your source. For roblox-ts projects, it
+> maps through source maps to show TypeScript lines.
+
+## Test file patterns
+
+The tool finds test files by these patterns (you can change them with
+`testMatch`):
+
+- TypeScript: `*.spec.ts`, `*.test.ts`, `*.spec.tsx`, `*.test.tsx`
+- Luau: `*.spec.lua`, `*.test.lua`, `*.spec.luau`, `*.test.luau`
+- Type tests: `*.spec-d.ts`, `*.test-d.ts`
+
+## Project structure
+
+```text
+jest-roblox-cli/
+├── bin/              CLI entry point
+├── src/
+│   ├── backends/     Open Cloud and Studio backends
+│   ├── config/       Config loading and validation
+│   ├── coverage/     Coverage instrumentation pipeline
+│   ├── formatters/   Human, JSON, and compact output
+│   ├── reporter/     Result parsing and validation
+│   ├── source-mapper/ Luau-to-TypeScript error mapping
+│   ├── snapshot/     Snapshot file handling
+│   ├── typecheck/    Type test runner
+│   ├── types/        Shared type definitions
+│   └── utils/        Helpers (glob, hash, cache, paths)
+├── luau/             Luau code that runs inside Roblox
+├── plugin/           Roblox Studio WebSocket plugin
+└── test/             Test fixtures and mocks
+```
+
+## Contributing
+
+### Build
+
+```bash
+pnpm build         # Full build
+pnpm watch         # Watch mode
+pnpm typecheck     # Check types
+```
+
+### Test
+
+```bash
+vitest run                    # All tests
+vitest run src/formatters     # One folder
+vitest run src/cli.spec.ts    # One file
+```
+
+### Lint
+
+```bash
+eslint .
+```
+
+> [!IMPORTANT]
+> This project keeps 100% test coverage. Write tests before you write code. Every pull request must keep full coverage.
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { t as CliOptions } from "./schema-ua9HqdbX.mjs";
+import { t as CliOptions } from "./schema-CG-f4OUB.mjs";
 
 //#region src/cli.d.ts
 declare function parseArgs(args: Array<string>): CliOptions;