Testing and tooling

The Template's verification commands, mirrored spec tree, pure-module coverage, service specs over engine substitutes, architecture checks, Studio checks and release pipeline.

Roblox Template / The Roblox Template

lune run check is the Template's verification pass and runs the same checks CI uses. After the sourcemaps, the groups run side by side (the lints in order, each type check, the specs in four shards, coverage); each stops at its first failing step, the run fails naming every failed step, and every step's time is printed at the end. A step whose tool is not installed is a failed step that says so and points at lune run doctor. lune run build then proves Rojo can build each configured place; lune run tree shows whether modules landed where expected. These commands complement the human Studio and testing-place checks.

The checks that run before review

  1. Run check

    lune run check generates each place's sourcemap; runs Selene, StyLua, boundary lint, the spec guard (lint-specs), leftover merge conflict markers (lint-conflicts), skill-mirror checks, vault links, module diagnostics, catalog validation, actionlint and history secret scanning; checks strict types (Roblox definitions for src, Lune's for tests, .lune and .agents/hooks); then runs the specs and coverage. History scanning is skipped in a copy without a git repository. In CI, where CHECK_BASE names the commit the change starts from, the skill-mirror check, vault links and actionlint run only when their files changed, and the secret scan reads only the new commits.

  2. Build the places

    lune run build writes build/game.rbxl for the start place and build/game-<name>.rbxl for the others. Pass a place name to build one. default.project.json ignores *.spec, *.test and wally.toml files, and a package's spec or test module found in the build fails it, so publish cannot ship one. Each build is then audited for streaming: persistent models within Config/Streaming.persistentBudget and each with a StreamingReason attribute, tagged models with a deliberate ModelStreamingMode, and a target radius above the minimum (Streaming). A breach fails the build.

  3. Inspect the tree

    lune run tree [place] [--scripts] prints the build's instance tree. Check the new module's location and that the place's slice is included.

  4. Request the runtime checks

    Follow the playtest skill: state what to open, what to do and what must happen, including refusal and rejoin for saved behaviour. Report every check run and every check still needing a person.

lune run doctor checks every tool in rokit.toml, git (required), the GitHub CLI and whether the commit message hook is switched on (a warning each), generated files, configuration and secrets, and in a game whether a newer Template release is out; lune run install refreshes Wally packages, sourcemaps and package types after dependency changes. Rokit pins the tools in rokit.toml; do not solve a type error by quietly changing their versions.

Specs mirror the source

Specs live in tests/**/*.spec.luau, in a tree that mirrors src/: the spec of src/core/shared/Util/Format.luau is tests/core/shared/Util/Format.spec.luau, a second spec of the same module is <Module>.<topic>.spec.luau beside it, and the .lune/ tools' specs are in tests/tools/. tests/lib/ holds the shared helpers, and tests/main/ is the game's own. Every require in a spec goes through the aliases in tests/.luaurc: @src (src/), @test (tests/) and @tools (.lune/), so a spec reads the same at any depth.

Luau
--!strictlocal T = require("@tools/lib/test")local Pricing = require("@src/core/shared/Rules/Pricing")T.describe("Rules.Pricing", function()    T.it("exponential curve", function()        T.expect(Pricing.exponential(100, 1.15, 10)).toBe(405)    end)end)

.lune/lib/test.luau is the house library: describe and it, hooks (T.beforeEach, T.afterEach, T.beforeAll, T.afterAll), T.it.only, T.it.skip, T.it.each, tags, T.fn spies, and matchers including toEqual (naming the first differing key path), toMatchObject, and toBeOk and toBeErr for a Result. The full list is in the Template's tests/README.md and docs/engineering/Testing.md.

lune run test [pattern] [flags]

patterntext
Only the spec files whose path contains it, such as lune run test Pricing. A pattern that matches no spec file exits 1.
--nametext
Only cases whose full name (Suite > case) contains the text.
--tag, --skip-tagtag
Only, or all but, the cases with a tag; repeatable.
--bailflag
Stop at the first failure.
--listflag
Name the cases that would run, with their tags, and run none.
--changedflag
Only the specs that reach a file this branch changed against its merge-base with main.
--watchflag
Run again in a fresh Lune whenever a file under tests/, src/ or .lune/ changes.
--verboseflag
Print every file and case; the runner is quiet by default.
--shardi/n
Only the i-th of n parts of the spec files, split by the time each file took in the last check (build/spec-times.json; with no times yet, every n-th file) so the parts finish together.

Flags work with a pattern either way: lune run test Pricing --bail and lune run test Pricing -- --bail are the same. lune run check runs the specs in four shards side by side, each in its own Lune process, so a spec must not share a file on disk with another spec.

Every case carries its folder's tag: unit under tests/core/shared/, service under tests/core/server/, tests/core/client/ and tests/core/bootstrap/ (the loading screen), tool under tests/tools/. Slow specs tag themselves slow (the template-update and init runs, the charts) and measured scenarios perf, so --skip-tag slow --skip-tag perf is the quick loop. An it.only fails under CI, and CI always runs the whole suite with no flags.

Pure modules need full line coverage

Pure Util, Rules, Config, PlayerData, AccountData and Types modules never touch Roblox APIs. They use string requires so Lune can load them. Inject time, randomness and waits into rules, making cases deterministic. Any rule that can break the economy or progression arrives with its spec.

Coverage runs the specs under the official Luau CLI because Lune does not supply coverage. lune run coverage requires 100% of executable lines in the pure-module set; lune run coverage -- --report shows unreached lines. Specs that count toward coverage therefore use only the Luau standard library and the test library, without @lune/... requires or task; a spec that requires a tests/lib helper runs under lune run test only.

Services and controllers have specs too

A service or controller is tested by a spec that runs its actual source over substituted boundaries: tests/lib/runtime (signals, atoms, clock, troves), the engine kit in tests/lib/engine (Players, DataStores with a ProfileStore stand-in, MessagingService, remotes, and the Http and MemoryStore modules), tests/lib/services for the save, currency, remotes and admin registry most services stand on, and tests/lib/client for controllers. DataService itself is specced over the ProfileStore stand-in.

Every server service's spec covers its start with the feature on and off, its main path, at least one refusal that writes nothing, and cleanup when a player leaves; specs over tests/lib/services also run a perf-tagged soak over repeated joins and leaves. Every controller with logic has at least a smoke spec. lune run lint-specs, part of check, fails when a module in Services/ or Controllers/ is neither loaded by a spec nor listed in its UNTESTED table with a reason (engine shells only, or a gap with a Backlog line), and when a listed one is now loaded, so the list only shrinks. lune run coverage -- --services reports each service's and controller's share of statements run, lowest first; it is a heuristic report, not a gate, and not part of check.

Interface and cost specs run the installed Fusion and Charm over counted engine doubles (tests/lib/ui): Screens.profiles opens, idles, updates and cycles every window and screen App can open and fails if one animates at rest or keeps instances, Screens.phone guards the phone layout at an iPhone SE viewport, Theme.access holds the Theme's colours to WCAG AA, SyncService.traffic checks that an idle server sends nothing, Economy.load runs 100 players through the real quest, season pass, playtime, Premium, daily reward and title services and holds the save writes per player and per earn (earning forces no save, an account claim two, a repeat nothing, no timer per player), AntiCheatService.load runs the anti-cheat's hot paths with 1, 20 and 100 players (the Network check per remote call, the Economy check per currency change, observeAction per action) and requires that honest load raises nothing (ANTICHEAT_LOAD=1 prints the cost per call), AntiCheatService.movementCost holds the movement check's spatial queries per player within its budgets, and Loader.startupCost checks that a switched-off module starts nothing and that, with the switches as written, the client requires none of the developers' diagnostics until one runs. Layout.responsive holds the HUD layout's rules on 24 screens and through window sweeps a pixel at a time. lune run startup [-- server|client] [--errors] prints both sides' startup cost through the Loader (files, modules started, connections, instances, remote handlers, require, init and start times), with the switches as written and all off. These are operation counts under a controlled clock, not frame time.

What boundary lint protects

lune run lint-boundaries keeps remotes, stores, purchases, analytics, teleporting and interface construction in their designated owners. It also rejects client access to server containers, impure shared rules, missing strict headers, per-frame handlers without a FrameBudget label, interface springs created outside UI/Util/motion, hand-written asset ids, UI rule imports, orphaned place slices, hard-coded player text in interface code and string keys that Config/Strings lacks. See the architecture boundaries.

Other useful commands are lune run format, lune run lint-links, lune run catalog, lune run modules, lune run lint-conflicts, lune run perfdiff <before> <after> (two perfrecord captures compared, failing on a broken performance budget; see the admin suite) lune run strings (the localization table CSV for the Creator Hub), and lune run bench [-- <filter>], micro-benchmarks of the shared utilities and rules on hot paths (TableUtil, BigNum, Format, Localize.text, Scheduler, RateLimiter, Cooldown, FrameBudget.wrap, WeightedRandom, Particles, the keyed row compare, Layout.solve and Layout.clean, the 4 to 5 save migration, and PlayerList.order on a 700-player server), best of three runs, only those whose name matches the filter. Bench numbers are Lune time on one machine, so compare a change with the code before it as a ratio; it is not part of check.

Every file starts with --!strict and no other directive: the Template uses neither --!native nor --!optimize 2. A game with a real numeric hot loop marks that one function @native after profiling it in Studio with and without (docs/engineering/Performance.md, "Compiler directives"). lune run skills-sync copies .agents/skills and .agents/reviewers into .claude/ for Claude Code; check refuses drift.

What automatic tests cannot prove

Physics, rendering, networking, live DataStores and MarketplaceService's purchase flow need Roblox's runtime. Service and interface specs substitute them and claim nothing about them. The reviewer runs a Studio smoke test, and releases are played in the testing place. Real saves need a rejoin; purchase changes need their real receipt checks; device UI needs the relevant input hardware.

The Template's docs/testing/Playtest Checklist.md is the person's pass: the smoke test (in setups 1, 3 and 4, about ten minutes with the admin console) after any change to loading, sync, saving, UI plumbing or packages and before every release, and every other Studio, device and testing-place check a Review card still needs, grouped by setup, including a memory soak on a live server (leaks start, repeated joins, windows and fixtures, then leaks and instances back to the first reading). Beside it, docs/testing/ holds the audits a release re-reads: Save, Security, Compliance, Analytics Coverage, Accessibility and Cross-device. A launch copies the launch checklist in docs/engineering/Roblox Platform Rules.md, which holds the Template's content-ratings answers.

A bug becomes either a failing spec or a reproducible Studio step before the fix. Keep the spec afterwards, and add a lasting runtime regression step to the playtest checklist where appropriate.

How a checked change becomes a release

Commit and squash-PR titles feed release-please. It maintains one release PR with the version and CHANGELOG; that same PR updates the line marked x-release-please-version: in a game in Config/Overrides/Game.luau, in the Template in Config/Game.luau. A fix or balance change is a patch, a feature is a minor, and a breaking change is minor before 1.0 or major afterwards. Never hand-edit version or CHANGELOG.

In the Template, a breaking (!) pull request also adds a note to docs/upgrading/ with the steps a game takes: the squash commit carries only the title, so the note is where the steps travel. lune run template-update prints those notes first when a game takes the release (Taking Template updates).

From a merged change to a live place. Changes merge through reviewed pull requests. release-please opens the version and changelog pull request. Merging that release creates a tag and GitHub release and publishes configured testing places. People play the release in testing, fix issues forward and authorize the publish-live workflow before watching the live game.

For an authorized developer, lune run publish -- testing or lune run publish -- live --yes checks, builds and uploads configured places through rbxcloud using ROBLOX_API_KEY from the environment or the git-ignored .env. --place <name> selects one. It refuses an unknown argument, two targets, and --place naming no configured place; lune run experience -- sync likewise refuses unknown flags. The lead can use Actions' publish-live workflow and type live; after it publishes, the workflow runs lune run release-record, which records the version and its changelog notes in the game's release log on the platform (POST /developer/v1/game/releases with the BLOCKOUT_API_KEY secret of the live environment). Without the secret that step is skipped with a notice, and a failed record is a warning that never fails the publish. Agents are denied direct publishing; describing a command here does not perform it.

Rollback uses the previous published version in Creator Dashboard. An older build refuses a save already migrated beyond its schema version, so inspect save-format changes and prefer fixing forward when needed. The full procedure lives in docs/engineering/Release Process.md and the release skill.

Updated