This is an example of a Roblox project that uses TestEZ for unit testing and Selene for linting. A GitHub action is run to automatically run linting and unit tests. See the .github/workflows/ci.yaml file for the GitHub action declaration.
src/- Contains all the source code for the gametest/- Contains all unit testsPackages/- Dependencies installed from Wally (only generated after runningwally install)ci.lua- Used by the CI process to run the tests (will be run in the context of a Roblox plugin)default.project.json- Rojo configurationforeman.toml- Foreman configurationselene.toml- Selene configurationroblox.toml- Generated by Selenetestez.toml- Add Selene rules for TestEZwally.toml- Project dependencies
Roblox Studio is needed in order to run the TestEZ unit tests. The roblox-win-installer-action is used to run this installation process. The GitHub repo must have a ROBLOSECURITY secret assigned in order for this to work properly. Due to the high security risk of such a token, it is recommended that a burner account is created for this token.
Foreman is a toolchain manager for Roblox development. With Foreman, other build dependencies can be installed, which can also be seen in the foreman.toml file:
- Wally (Package manager)
- Selene (Linting)
- Rojo (Project management tool)
- run-in-roblox (Run a script in a Roblox Studio instance)
The wally install command is run to install all dependencies listed in the wally.toml file. These are placed into the Packages directory at the project root level.
In order for unit testing to take place via TestEZ, a Roblox place file needs to be generated with our main code and tests. The rojo build command is utilized to create this file, which will then be used by the run-in-roblox tool.
Once the place file is generated, unit tests are run using run-in-roblox. The ci.lua script is passed to the tool. This works by opening up Roblox Studio and running the ci.lua script in the context of a plugin. Any output generated by the process (e.g. calls to print) are returned by the tool and can be written to a file. In this example, results are written to test-out.txt.
The test-out.txt file is searched to look for "0 failed, 0 skipped", which would indicate that TestEZ succeeded. If so, the process exits successfully. Otherwise, the process will fail and the GitHub action will be shown in a failure state. In the case of a test failure, the test-out.txt file will be outputted within the logs of the GitHub action at this stage.
Linting is done with Selene against the src directory.
Linting should only be done against code written for the project, hence why Selene is not run against the whole project directory. Running the linter against vendor code (e.g. dependencies installed from Wally) could result in linting errors that don't pertain to the project.