{"id":"austinbarikdar/lunetest","name":"lunetest","scope":"austinbarikdar","platform":"roblox","description":"Test your Roblox game from the terminal: fast unit tests in Lune, real Studio for e2e, Open Cloud for CI.","version":"0.1.4","latest":"0.1.4","versions":["0.1.0","0.1.1","0.1.2","0.1.3","0.1.4"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"74baafbcee0584607d9b85326aead9a71f29923e07fb6247806ddbbdf996dfd7","likes":0,"downloads":1,"install":"forest install austinbarikdar/lunetest","url":"https://forest.dev/p/roblox/austinbarikdar/lunetest","files":"https://api.forest.dev/ai/package/roblox/austinbarikdar/lunetest/files","readme":"<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/AustinBarikdar/LuneTest/main/docs/logo.svg\" width=\"104\" alt=\"LuneTest logo\">\n\n# LuneTest\n\n**Test your Roblox game from the terminal.**\n\nOne command runs your specs. Plain logic finishes in milliseconds without opening Studio,<br>\nand tests that need the real engine run in Studio or on Roblox's own servers.\n\n[![CI](https://github.com/AustinBarikdar/LuneTest/actions/workflows/test.yml/badge.svg)](https://github.com/AustinBarikdar/LuneTest/actions/workflows/test.yml)\n[![Wally](https://img.shields.io/badge/wally-austinbarikdar%2Flunetest-f4e9c1?labelColor=1b2550)](https://wally.run/package/austinbarikdar/lunetest)\n[![License: MIT](https://img.shields.io/badge/license-MIT-4ade80?labelColor=1b2550)](LICENSE)\n[![Strict Luau](https://img.shields.io/badge/luau---!strict-9db4ff?labelColor=1b2550)](#writing-specs)\n\n[**Website**](https://austinbarikdar.github.io/LuneTest/) · [Quick start](#quick-start) · [Writing specs](#writing-specs) · [Simulated network](#simulated-network-unit-specs) · [CI/CD](#cicd) · [AI agents](#ai-coding-agents) · [Contributing](#contributing)\n\n</div>\n\n> [!WARNING]\n> **LuneTest is still in development.** Expect bugs, rough edges, and changes between versions while it is at 0.x. It is tested mostly on macOS; Windows support is newer and less proven. If something breaks, please [report it](https://github.com/AustinBarikdar/LuneTest/issues/new/choose). Bug reports and fixes are what make it stable.\n\n```\n$ lune run test\n  PASS  [unit] Economy/CoinsSpec › adds coins\n  PASS  [unit] Network/PacketsSpec › batched packets go client -> server -> client\n  FAIL  [unit] Economy/CoinsSpec › rejects negative amounts\n        ReplicatedStorage.LuneTestSpecs.Unit.Economy.CoinsSpec:12: expected function to throw\n  PASS  [server] ExampleServerSpec › runs on the server  (lune)\n[lunetest] 2 of 3 e2e specs need Studio\n[lunetest] running in Studio (in the background)...\n  PASS  [server] Combat/RaycastSpec › ray into empty space hits nothing  (studio)\n  PASS  [client] HudSpec › PlayerGui exists  (studio)\n\n[lunetest] 5 passed, 1 failed (8.06s)\n```\n\n## Why LuneTest\n\n<table>\n<tr>\n<td width=\"33%\" valign=\"top\">\n\n### Fast by default\n\nUnit specs run inside Lune against your Rojo-built place. No Studio, and 6,000 tests take about 0.2 seconds.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### Real when it matters\n\nSpecs that need the engine run in a real Studio Play session, with a real server, client and character. Studio starts in the background and closes itself.\n\n</td>\n<td width=\"33%\" valign=\"top\">\n\n### Works in CI\n\nServer specs run on Roblox's own servers through Open Cloud, with no Studio. Your place is never changed.\n\n</td>\n</tr>\n<tr>\n<td valign=\"top\">\n\n### Lune first\n\nEvery e2e spec is tried in Lune before Studio opens. Only the ones that fail there go to Studio, whose result is final.\n\n</td>\n<td valign=\"top\">\n\n### Network without Studio\n\nClient and server code run together inside Lune, with working remotes and per-frame packet batching.\n\n</td>\n<td valign=\"top\">\n\n### Agent-ready\n\nSetup installs a skill that teaches Claude Code and Codex to write good specs.\n\n</td>\n</tr>\n</table>\n\n## Quick start\n\nFrom your Rojo project's folder, one command sets everything up and runs the example tests:\n\n**macOS / Linux (Terminal):**\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/AustinBarikdar/LuneTest/main/install.luau | lune run -\n```\n\n**Windows (PowerShell):**\n\n```powershell\ncmd /c \"curl -fsSL https://raw.githubusercontent.com/AustinBarikdar/LuneTest/main/install.luau | lune run -\"\n```\n\nAfter that:\n\n```sh\nlune run test          # everything\nlune run test unit     # only the fast specs, no Studio\n```\n\nThere are two kinds of test, decided by the folder a spec is in:\n\n| Kind | Folder | Runs | Speed |\n| --- | --- | --- | --- |\n| **unit** | `tests/unit/` | Inside Lune, against your Rojo-built place. No Studio. | milliseconds |\n| **e2e** | `tests/e2e/{server,client,shared}/` | Tried in Lune first. Any spec that fails there is rerun in a real Studio Play session. | Instant if Lune passes, ~8s if Studio is needed |\n\nStudio only opens when at least one e2e spec actually needs it. It runs in the background in its own instance, and that instance closes when the run is over. A Studio you already have open is left alone.\n\nThe exit code is 0 when everything passes and 1 when something fails, so it works in scripts and CI.\n\n## Contents\n\n- [Requirements](#requirements)\n- [Setup](#setup)\n- [Running](#running)\n- [Writing specs](#writing-specs)\n- [Lune first, Studio fallback](#lune-first-studio-fallback-e2e-specs)\n- [Simulated network](#simulated-network-unit-specs)\n- [Remotes table](#remotes-table)\n- [CI/CD](#cicd)\n- [AI coding agents](#ai-coding-agents)\n- [Config](#config)\n- [Reliability on slow machines](#reliability-on-slow-machines)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [Credits](#credits)\n- [Developing LuneTest](#developing-lunetest)\n\n## Requirements\n\n- [Rojo](https://rojo.space) 7, [Lune](https://lune-org.github.io/docs) **0.10 or newer** and [Wally](https://wally.run). If your project pins an older Lune, LuneTest's setup updates the pin for you and tells you to run `rokit install`. With [Rokit](https://github.com/rojo-rbx/rokit): `rokit init` (if the project has no `rokit.toml` yet), then `rokit add rojo`, `rokit add lune`, `rokit add wally`.\n- For e2e specs only: Roblox Studio on macOS or Windows, signed in.\n\n## Setup\n\nFrom your project root, one command does everything. Use the one for your system:\n\n**macOS / Linux (Terminal):**\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/AustinBarikdar/LuneTest/main/install.luau | lune run -\n```\n\n**Windows (PowerShell):**\n\n```powershell\ncmd /c \"curl -fsSL https://raw.githubusercontent.com/AustinBarikdar/LuneTest/main/install.luau | lune run -\"\n```\n\nIt adds LuneTest to `wally.toml` (creating the file if you don't have one), runs `wally install`, sets the project up, and runs the example unit tests so you can see it working. If Rojo or Wally is missing, it installs them with Rokit. It's safe to run again.\n\nThe Windows command goes through `cmd` on purpose. In a UTF-8 console (code page 65001), Windows PowerShell puts a byte-order mark in front of anything it pipes, and Lune stops with `got Unicode character U+feff`.\n\n### Easy download integration for Wally\n\nAlready use Wally? Add LuneTest like any other package:\n\n1. Add LuneTest to `wally.toml`:\n\n   ```toml\n   [dev-dependencies]\n   LuneTest = \"austinbarikdar/lunetest@0.1.0\"\n   ```\n\n2. Download it (same on every system):\n\n   ```sh\n   wally install\n   ```\n\n3. Run the LuneTest `init`, from your project root. You only do this **once per project**. This command differs by system:\n\n   **macOS / Linux (Terminal):**\n\n   ```sh\n   lune run DevPackages/_Index/*/lunetest/lune/init.luau\n   ```\n\n   **Windows (PowerShell):**\n\n   ```powershell\n   lune run (Resolve-Path DevPackages/_Index/*/lunetest/lune/init.luau)\n   ```\n\n4. Run your tests (same on every system):\n\n   ```sh\n   lune run test\n   ```\n\nAfter that first run you never need `init` again:\n\n- **Updating LuneTest is just `wally install`.** The launcher always loads whichever version is installed.\n- **Teammates don't run it.** The launcher and tests are committed with your project, so after cloning they only need `wally install`.\n\nRunning `init` again is harmless. It never overwrites anything and only adds files that are missing. It creates:\n\n- **`.lune/test.luau`**: the launcher and your config. If you already have a `lune/` folder, it goes at `lune/test.luau` instead.\n- **`tests/`**: example unit and e2e specs.\n- **`.gitignore` entries**: for the generated `lunetest.project.json`, `lunetest.rbxl`, `lunetest.cache.json` and `lunetest.lock`, plus the `lunetest.rbxl.lock` Studio leaves behind on Windows.\n- **A skill for AI coding agents**: `.claude/skills/lunetest-testing/` for Claude Code and `.agents/skills/lunetest-testing/` for Codex. See [AI coding agents](#ai-coding-agents).\n- **The Studio plugin**: `LuneTest.rbxmx` in your Studio Plugins folder. No restart is needed: each test run opens its own Studio process, which loads it.\n\nLune runs `lune/test.luau` before `.lune/test.luau`. If you already have a `lune/test.luau`, `init` tells you instead of writing a second launcher that would never run.\n\n## Running\n\n```sh\nlune run test                        # everything\nlune run test unit                   # unit specs only (no Studio)\nlune run test e2e                    # e2e specs only\nlune run test unit Economy           # tests whose name contains \"Economy\"\nlune run test unit Economy Network   # ...or \"Network\"\nlune run test e2e server             # e2e tests whose name contains \"server\"\nlune run test --fresh                # retry every e2e spec in Lune, ignoring the cache\nlune run test --cloud                # CI: server/shared e2e specs on Roblox's servers, no Studio\n```\n\nA test's full name is `[kind] Group/SubGroup/SpecName › test name`. Any subfolder is a group, so filters can pick a folder, a spec file or a single test.\n\n## Writing specs\n\nA spec is a ModuleScript whose name ends in `Spec`. Everything in LuneTest is written in `--!strict`, including `expect` and `LuneTest.network`, so your specs can be too. It returns a table of named test functions. Other modules in the spec folders are treated as helpers and never run.\n\n```lua\n--!strict\n-- tests/unit/Economy/CoinsSpec.luau\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal expect = require(ReplicatedStorage.LuneTest).expect\nlocal Coins = require(ReplicatedStorage.Shared.Coins)\n\nreturn {\n\t[\"adds coins\"] = function()\n\t\texpect(Coins.add(10, 5)).toBe(15)\n\tend,\n\n\t[\"rejects negative amounts\"] = function()\n\t\texpect(function()\n\t\t\tCoins.add(10, -1)\n\t\tend).toThrow(\"must be positive\")\n\tend,\n}\n```\n\n| Folder | Runs on | Lives in the test place at |\n| --- | --- | --- |\n| `tests/unit` | Lune | `ReplicatedStorage.LuneTestSpecs.Unit` |\n| `tests/e2e/server` | Studio server | `ServerScriptService.LuneTestSpecs.Server` |\n| `tests/e2e/shared` | Studio server | `ReplicatedStorage.LuneTestSpecs.Shared` |\n| `tests/e2e/client` | Studio client | `ReplicatedStorage.LuneTestSpecs.Client` |\n\nEach test runs in its own thread with a timeout (`testTimeout`, default 30s). A stuck `WaitForChild` fails only that test instead of hanging the whole run. Tests run in name order.\n\n### Matchers\n\n`toBe`, `toEqual` (deep), `toBeTruthy`, `toBeFalsy`, `toBeNil`, `toBeA(typeName)`, `toBeCloseTo(n, epsilon?)`, `toBeGreaterThan`, `toBeLessThan`, `toContain` (works on arrays and substrings), and `toThrow(substring?)`.\n\nPut `.never` in front of any matcher to negate it: `expect(x).never.toBeNil()`.\n\n### What unit specs can use\n\nUnit specs get:\n- **The Rojo-built place:** `game`, `workspace`, `script`, and `require` of any ModuleScript in it.\n- **Lune's Roblox types:** `Instance`, `Vector3`, `CFrame`, `Enum` and the rest.\n- **`task`.**\n- **The simulated network** (below).\n\nEngine behavior is not there: no physics, no characters, no DataStores. Put tests that need those in `e2e`.\n\n## Lune first, Studio fallback (e2e specs)\n\nMany specs written for Studio pass in Lune too. So LuneTest tries every e2e spec in Lune first:\n\n```\n  PASS  [server] ExampleServerSpec › runs on the server  (lune)\n[lunetest] 2 of 3 e2e specs need Studio\n[lunetest] running in Studio...\n  PASS  [server] Combat/RaycastSpec › ray into empty space hits nothing  (studio)\n  PASS  [client] ExampleClientSpec › has a character  (studio)\n```\n\n- **In Lune:** server and shared specs run as the simulated server, and client specs run as the simulated client.\n- **A spec with any failure in Lune is rerun in Studio.** This covers a real bug, a missing engine feature like `workspace:Raycast`, and a character that doesn't exist. Studio's result is final, so a gap in Lune can never produce a false failure.\n- **The Lune attempt is fast.** A spec stops at its first failure, and each test gets 5 seconds, so specs that need Studio hand over quickly.\n- **Studio only runs the specs that fell back,** and it doesn't open at all if everything passed in Lune.\n- **Each line says where the test ran:** `(lune)` or `(studio)`.\n- **Studio-only specs are remembered.** LuneTest saves which specs needed Studio in `lunetest.cache.json`, keyed by a fingerprint of each spec file. On the next run they go straight to Studio without retrying in Lune. Editing a spec file makes LuneTest retry it in Lune.\n- **`lune run test --fresh` retries everything in Lune.** The fingerprint only covers the spec file itself, so use this after fixing a module a cached spec depends on.\n\nSet `fallback = false` in the config to always run e2e specs in Studio.\n\n## Simulated network (unit specs)\n\n`LuneTest.network` runs client and server code together inside Lune, so networking and packet code can be tested without opening Studio.\n\n```lua\n--!strict\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal LuneTest = require(ReplicatedStorage.LuneTest)\nlocal expect, network = LuneTest.expect, LuneTest.network\n\nreturn {\n\t[\"client -> server -> client\"] = function()\n\t\tlocal fromPlayer, echoed\n\t\tnetwork.server(function()\n\t\t\tlocal Packets = require(ReplicatedStorage.Shared.Packets)\n\t\t\tPackets.on(\"Hello\", function(data, player)\n\t\t\t\tfromPlayer = player\n\t\t\t\tPackets.send(\"Echo\", { n = data.n + 1 })\n\t\t\tend)\n\t\tend)\n\t\tnetwork.client(function()\n\t\t\tlocal Packets = require(ReplicatedStorage.Shared.Packets)\n\t\t\tPackets.on(\"Echo\", function(data)\n\t\t\t\techoed = data\n\t\t\tend)\n\t\t\tPackets.send(\"Hello\", { n = 1 })\n\t\tend)\n\n\t\tnetwork.flush()\n\t\texpect(fromPlayer).toBe(network.player())\n\t\texpect(echoed).toEqual({ n = 2 })\n\tend,\n}\n```\n\n| API | What it does |\n| --- | --- |\n| `network.client(fn, ...)` | Runs `fn` as the client and returns what it returns. `RunService:IsClient()` is true and `Players.LocalPlayer` is set. |\n| `network.server(fn, ...)` | Runs `fn` as the server. Spec code outside either call also counts as the server. |\n| `network.flush(frames?)` | Waits a few frames (default 3) so queued remotes and `Heartbeat` batches get delivered, then re-throws any error a handler hit. |\n| `network.spy(remote)` | Returns a live list of `{ direction = \"toServer\" \\| \"toClient\", args = {...} }` for everything sent through `remote`. |\n| `network.player()` | The simulated player. It joins, firing `Players.PlayerAdded`, the first time client code runs. From then on, `Players.LocalPlayer` is set for server code too (one shared `Players` service). |\n\nHow it behaves:\n- **Modules load once per side.** Code inside `network.client` gets its own copy of every module, just like a real client.\n- **Remotes behave like Roblox.** `RemoteEvent`, `UnreliableRemoteEvent` and `RemoteFunction` (`FireServer`, `FireClient`, `FireAllClients`, `InvokeServer`, `InvokeClient`) deliver on the next frame and copy their arguments. Events sent before anyone connects are queued.\n- **Frame events tick.** `RunService.Heartbeat`, `Stepped`, `PostSimulation` and the other frame events fire every frame, so packet libraries that batch per frame (ByteNet, Packet, custom ones) work without any setup.\n- **Handler errors fail the test.** If a remote handler errors, the next `network.flush()`, `network.client()` or `network.server()` fails with that error.\n\n### Custom packet handlers\n\nNo setup is needed for libraries built on remotes. If your packet module lets you replace its transport, you can test the logic without remotes instead. Call the server handler directly inside `network.server(function() ... end)` with the data your client code produced in `network.client`.\n\n## Remotes table\n\nIf your game keeps its remotes in a table, declare it in the launcher config. LuneTest creates the instances in the test place, so they exist in unit **and** e2e runs:\n\n```lua\nremotes = {\n\t[\"ReplicatedStorage.Remotes\"] = {\n\t\t\"Chat\",                        -- a bare name is a RemoteEvent\n\t\tGetData = \"RemoteFunction\",\n\t\tMove = \"UnreliableRemoteEvent\",\n\t},","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/austinbarikdar/roblox/lunetest/0.1.4/readme"}