GLuaTest

<p align="left"> <a href="https://discord.gg/5JUqZjzmYJ" alt="Discord Invite"><img src="https://img.shields.io/discord/981394195812085770?style=flat-square&logo=discord&logoColor=white&label=Support" /></a> <a href="https://github.com/CFC-Servers/GLuaTest/actions/workflows/self_tests.yml" alt="GLuaTest Status"><img src="https://img.shields.io/github/actions/workflow/status/CFC-Servers/GLuaTest/self_tests.yml?branch=main&logo=lua&logoColor=white&style=flat-square&label=Self%20Tests" /></a> <a href="https://github.com/CFC-Servers/GLuaTest/actions/workflows/self_tests.yml" alt="GLuaTest Status"><img src="https://img.shields.io/github/v/tag/CFC-Servers/GLuaTest?sort=semver&style=flat-square&logo=github&logoColor=white&label=Version" /></a> </p>

🎉 <strong>The missing test framework for GMod</strong> 🎉

GLuaTest is a testing framework built for Garry's Mod. Its job is to make writing automated tests for Garry's Mod projects easy and tolerable.

It offers an approachable and flexible syntax that makes writing tests intuitive.

GLuaTest takes a lot of inspiration from both Ruby's RSpec and JavaScript's Jest

Glossary

• Additional reading
• Usage
• Writing Tests
• Troubleshooting
• Developers

---

(Are you an impatient software developer? Check out the quickstart guide to go fast)

(Is the idea of testing your code new to you? That's great! Check out the guided testing walkthrough to see some great examples of how to test real code)

<br>

Features

Simple test setup and quirky (yet intuitive!) test syntax

-- lua/tests/project_name/main.lua

return {
    groupName = "MyProject",
    cases = {
        {
            name = "Should create project tables",
            func = function()
                expect( MyProject ).to.exist()
            end
        }
    }
}

Beautiful test output

<img src="https://user-images.githubusercontent.com/7936439/170405271-abbd745a-f9ca-48c5-8228-5160c8349a2c.png" width="725" height="300">

Handsome, informative error reporting

<br>

Some additional reading:

<details> <summary><strong>Foreword about automated testing in GMod</strong></summary> <br> Automated testing is a crucial part of any software workflow. Your automated tests define a contract that give you and your would-be users confidence that the project will behave properly.

Without tests, you may find yourself spending large amounts of time debugging obscure issues. Automated tests require more work up front, but will save you time and frustration in the future as your project grows.

---

Traditionally, Garry's Mod developers have included, at most, a few crucial tests with their codebase - usually only ran manually when the maintainer remembers. Modern testing infrastructure allow you to run your tests on a Pull Request, before the code has made it into the main branch.

Such a tool has never existed for Garry's Mod. Until now!

</details> <details> <summary><strong>Technical info</strong></summary> <br> GLuaTest was made to run on GitHub Actions, but it's flexible enough to fit anywhere you'd like.

You can use the GLuaTest Docker image to spin up a test server, run your tests, and see the output - all without having to install a server of your own.

This makes it easy to test your code in a real Garry's Mod environment without worrying about other addons or config values.

</details> <br>

Usage

GLuaTest can be used in a number of ways. Whether you want to run your tests when you open a PR, or if you just want to have it run on your development server - we've got you covered.

<br>

Automated testing on Pull Requests

<details> <summary><strong>Run your tests in a Pull Request</strong></summary> <br>

To set up automated test runs, we'll use GitHub Workflows.

It's actually really simple to set up the workflow. Add the following file to your project:

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main

And that's it! The next time you make a PR, it'll spin up a new test server, run your project's test, and report any failures in your PR.

There are a couple of config options you can use though.

---

Requirements

<details> <summary><strong>If your project depends on an external project, GLuaTest can automatically grab them for you</strong></summary> <br>

Let's say you needed:

• ULX
• ULib
• The Lua branch CFC's Logging Library ( https://github.com/CFC-Servers/gm_logger )

Make a new file somewhere in your project (i.e. lua/tests/my_project/requirements.txt) with the following:

TeamUlysses/ulx
TeamUlysses/ulib
CFC-Servers/gm_logger@lua

Each line should be in the format of: <Github owner name>/<Project name>.

You can use a specific branch of the project by adding @<branch-name> to the end of the line.

(If your requirement is hosted in a private GitHub repo, you'll need to do some annoying legwork to get everything connected. More info here.)

Great, now we update our workflow to use our requirements file

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main
    with:
      requirements: lua/tests/my_project/requirements.txt

All done! Commit those changes and GLuaTest will automatically clone your requirements.

</summary> </details>

---

Server Configs

<details> <summary><strong>Sometimes your project requires specific convars / server settings</strong></summary> <br>

Similar to how you define requirements, we'll make a new .cfg file.

This file will be dumped straight into the end of server's server.cfg file. You can override existing configs, too.

So, create the file:

# Example file name/location: lua/tests/my_project/server.cfg
my_convar 1
name "My favorite server"

Update the workflow:

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main
    with:
      server-cfg: lua/tests/my_project/server.cfg

And that's it!

</summary> </details> <br>

Gamemodes and Maps

<details> <summary><strong>You can customize which gamemode and map the server starts with</strong></summary> <br>

Simply specify the desired gamemode and/or map in your workflow's with section.

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main
    with:
      gamemode: darkrp
      map: rp_downtown_tits_v2

</summary> </details> <br>

Workshop Collection

<details> <summary><strong>To make dependency management easier, you can tell the test server to use a specific workshop collection.</strong></summary> <br>

Add the collection ID in your workflow's with section.

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main
    with:
      collection: 1629732176

</summary> </details> <br>

GMod Branch

<details> <summary><strong>You can run your tests on any of the GMod branches</strong></summary> <br>

Just set the branch input in your workflow:

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main
    with:
      branch: x86-64

Acceptable options are:

• live (Main GMod version - this is the default)
• x86-64
• prerelease
• dev

</summary> </details>

Extra Startup Arguments

<details> <summary><strong>You can give GLuaTest custom startup args to fine-tune your test setup</strong></summary> <br>

You can use the extra-startup-args input to pass any arguments you want to the srcds instance. For example:

name: GLuaTest Runner

on:
  pull_request:

jobs:
  run-tests:
    uses: CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@main
    with:
      extra-startup-args: "-tickrate 16 -usegh"

Note: These args are passed in before the base params, so you can override any of the base srcds arguments.

</summary> </details> <br>

All options

<details> <summary><strong>Here are all of the options you can pass to the workflow</strong></summary> <br>

| Name | Description | Example | |----------------------|------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------| | server-cfg | A path (relative to project directory) with extra server config options | data_static/my_addon.cfg | | requirements | A path (relative to project directory) with a list of all requirements to test this project | data_static/my_addon.txt | | gamemode | The name of the gamemode for the test server to run