roblox-test-runner 0.3.4

Execute Luau tests on Roblox Cloud

Roblox Test Runner

Roblox Test Runner is a powerful CLI tool designed to execute Luau tests (TestEZ) directly on Roblox Cloud. It allows you to run unit tests from your local machine and see the results instantly, integrating seamlessly into your development workflow.

Features

• 🚀 Run Tests on Cloud: Execute tests in a live Roblox server environment.
• 📦 Rojo Integration: Automatically respects your default.project.json structure.
• ⚙️ Configurable: Use roblox-test-runner.toml to customize paths, timeouts, and more.
• 🔄 Watch Mode: Automatically re-run tests when files change (-w).
• 🤖 CI/CD Ready: Native support for GitHub Actions authentication.

Installation

pip install roblox-test-runner

Quick Start

1. Initialize Configuration:

   roblox-test-runner init
   

   This creates a roblox-test-runner.toml file.

2. Set API Key (for local development):

   roblox-test-runner set-api <YOUR_API_KEY>
   

3. Run Tests:

   roblox-test-runner run
   

   or watch for changes:

   roblox-test-runner run --watch
   

Usage

Commands

• run [test_name]: Run tests. omit test_name to run all.
  • -v, --verbose: Show full logs.
  • -w, --watch: Watch mode.
  • -j, --json: JSON output.
• init: Create default configuration.
• config: View current configuration.
• set-api <key>: Save API key.
• auth: CI/CD authentication helper.

Configuration (roblox-test-runner.toml)

[runner]
timeout = 60
tests_folder = "tests"

[project]
rojo_project = "default.project.json"

Environment & Debugging

Execution Environment

Tests run in a Roblox Cloud headless environment. This has some important limitations:

• No Physics Simulation: Gravity and physics stepping do not run automatically.
• Headless: No visual rendering.
• Script Context: Tests run inside a temporary script, often referred to as TaskScript.

Debugging

The runner automatically maps stack traces from the bundled TaskScript back to your original source files (supported for .luau files managed by Rojo).

• If you see TaskScript:123, update to the latest version to see src/my_script.server.luau:45.
• Use print() debugging freely; logs are streamed back to your terminal.

API Keys

API keys can be provided in three ways (checked in order):

1. CLI Argument: roblox-test-runner run --key <KEY> (mostly for CI)
2. Environment Variable: ROBLOX_API_KEY
3. User Configuration: Saved via roblox-test-runner set-api <KEY> (stored in your user home directory, not project)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.