Skip to content

Testing your changes

Every pull request runs the same checks in CI. Run them yourself first, so the pull request is green before anyone reviews it.

You need pesde and Rokit installed (see Environment Setup). Then, from the repository root:

Terminal window
rokit install # installs the pinned tools; Rokit asks once before installing a tool it has not seen, answer yes
zune setup # writes the Zune type definitions
zune run .zune/bundle.luau # builds the api_types bundle
pesde install # installs package dependencies

Then run the checks in the order CI runs them. Seed the binary cache first, and again after any change to a binary or a checksum: opus always loads its own checksummed libopus, and until a version’s release tag exists its download fails with HTTP 404.

Terminal window
zune run .github/scripts/seedBinaryCache.luau # before the tests: copies the committed binaries into the cache
zune run .zune/fmt.luau # formatting (StyLua)
zune run .zune/lint.luau # linting (Selene)
zune run .zune/analyze.luau # type checking (luau-lsp)
zune run .zune/test.luau # every test

To test only the packages you changed, pass the package folder:

Terminal window
zune run .zune/test.luau packages/websocket

Some packages (dave, opus, sodium, symphonia) need FFI, which lets Luau call native libraries. Zune has it, and the seeded cache (or, once a release tag exists, the first test run’s download) supplies the library for your platform. On a runtime without FFI, their native tests show as skipped rather than failed. If you write a test that calls a native library, copy the start of packages/dave/tests/session.spec.luau: it fails loudly if the library cannot load, and skips the suite when FFI is missing. Do not call the library at the top of the file, because an error there stops the whole test run. When your pull request touches these packages, CI also runs their tests on Windows and macOS.

When you fix a bug, write a test that fails without your fix and passes with it.

  1. Write the test first and run it. It should fail, and fail for the reason the bug describes.
  2. Make the fix.
  3. Run the test again. It should pass.
  4. Put both results in the pull request description.

A test that passes before the fix proves nothing. It is the most common mistake in AI-written tests, so check it.

New behaviour needs tests that show it working, including the error cases. Changing behaviour means updating the tests that describe it.

  • Tests live in packages/<name>/tests/ and end in .spec.luau. They use frktest.
  • Split tests by what they cover: several small files, not one large one. For example, packages/websocket/tests has reconnect.spec.luau, resume.spec.luau and stayDown.spec.luau.
  • Do not write your own fake Discord. For anything that talks to the gateway or the REST API, use packages/discord_stub, a local Discord that runs on your machine. Its virtual clock runs 100 times faster than real time, so a test can wait through reconnect delays and heartbeats in a fraction of a second. If it is missing something your test needs, add it to the stub (with its own tests) instead of writing a fake in your test folder.
  • Do not add tests/support or tests/helpers folders. Shared test helpers belong in discord_stub.