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!

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.

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.

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

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

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

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

name: GLuaTest Runner

on:
  pull_request:

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

name: GLuaTest Runner

on:
  pull_request:

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

name: GLuaTest Runner

on:
  pull_request:

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

Running tests in a GitHub Runner is surprisingly fast.

Even with hundreds of tests, you can expect the entire check to take under 30 seconds!

(Failing async tests will slow down the time significantly because it has to wait for the timeouts)

You should incur no costs by using GitHub Actions.

Nothing better than free 😎

It's actually extremely simple to run GLuaTest locally.

Just put GLuaTest into your addons/ directory, set gluatest_enable 1 on the server, and restart!

All of your tests will run when the server starts up and you can view the output in the server console/logs.

Sounds weird, right? Well it's really not all that different from running GLuaTest on GitHub.

In fact, many of the steps are the same.

If your project depends on other projects, you can have GLuaTest automatically acquire them for you.

Take a quick skim through the GitHub Action setup instructions for the relevant sections on how to set this up.

When running GLuaTest without a server, you need to tell it where to find your project and custom files.

You can do that with simple environment variables, i.e.:

export REQUIREMENTS=/absolute/path/to/requirements.txt
export CUSTOM_SERVER_CONFIG=/absolute/path/to/server.cfg
export PROJECT_DIR=/home/me/Code/my_project
export GAMEMODE="sandbox"
export COLLECTION_ID="12345"
export SSH_PRIVATE_KEY="the-entire-private-key"
export GITHUB_TOKEN="a-personal-access-token"

• You can skip the REQUIREMENTS and CUSTOM_SERVER_CONFIG if you don't need them, but you must set the PROJECT_DIR variable.

• The GAMEMODE variable defaults to "sandbox", so you can omit it if that's appropriate for your tests.

• The COLLECTION_ID variable allows you to pass a workshop collection ID for the server to grab before starting.

• The SSH_PRIVATE_KEY variable is used when one or more of your Requirements are hosted on a Private Repository.

• The GITHUB_TOKEN variable, like the SSH_PRIVATE_KEY is also used to grant access to private repositories. Personal Access Tokens are a simpler (but ultimately worse) alternative to a full SSH keypair.

(Read more about privately-hosted project requirements: https://github.com/CFC-Servers/GLuaTest/wiki/Private-Requirements )

Now you'll need docker-compose. I'll leave it to you to figure out how to install it: https://docs.docker.com/compose/install/

Once that's done, you just need to run the docker-compose file in the docker/ directory.

On Linux/OSX, this looks like:

docker-compose up

And.. that's it! It'll pull the latest Runner, start the server, and run your tests. You can even follow the test output live.

Let's say your addon looks like this:

MyProject = {}

function MyProject.UserExistsInDatabase( user )
    local userObject = lookupUserInDatabase( user )
    return userObject.exists
end

function MyProject.CheckUser( user )
    if not MyProject.UserExistsInDatabase( user ) then return end
    if not user.name then return end
    if #user.name == 0 then return end

    return true
end

You want to test the functionality of CheckUser.

There are three checks in CheckUser:

• The user exists in the database
• The user's name exists
• The user's name is not empty

You could add a fake user to the database and use the function normally, but you're not testing the database, you're testing CheckUser.

Instead, we could pretend that UserExistsInDatabase returns true for our tests. We can do this using a Stub.

-- lua/tests/my_project/checkuser.lua

return {
    groupName = "CheckUser",
    beforeEach = function( state )
        state.validUser = { name = "Valid User" }
    end,

    cases = {
        {
            name = "Should return true with a valid User",
            func = function( state )
                stub( MyProject, "UserExistsInDatabase" ).returns( true )

                expect( MyProject.CheckUser, state.validUser ).to.beTrue()
            end
        },
        {
            name = "Should check if user exists in database",
            func = function()
                local dbCheck = stub( MyProject, "UserExistsInDatabase" ).returns( true )

                MyProject.CheckUser( state.validUser )

                expect( dbCheck ).to.haveBeenCalled()
            end
        }
    }
}

Now our CheckUser test only tests the functionality in CheckUser, and doesn't depend on any other function's correctness.

A Stub will replace the given function on the given table with a callable Stub object. The Stub keeps track of how many times it was called, and what parameters it was called with.

If you need to restore the original functionality of the stubbed function, you can use stub:Restore().

Un-restored stubs are automatically restored after each Test Case, but you can manually call :Restore() any time you need.

You can create an empty Stub that doesn't automatically replace anything by calling stub() with no arguments.

You can use the Stub like normal. This is particularly useful for functions that take callbacks, i.e.:

{
    name = "RunCallback should run the given callback",
    func = function()
        local myStub = stub()

        MyProject.RunCallback( myStub )

        expect( myStub ).to.haveBeenCalled()
    end
}

Restoring empty stubs is a no-op, but won't break anything.

You can tell your stubs what to return when they're called.

.with( function )

If you want to replace a function with another function, you can use the .with modifier.

When your stub is called, it will pass all of the parameters it received to the function you gave to .with, and will return whatever your given function returns.

.returns( ... )

If you just want to return a certain value every time your Stub is called, you can use the .returns modifier.

When your Stub is called, it will simply return everything you passed into .returns.

.returnsSequence( table sequence, any default )

If you need to specify a sequence of values that your stub will return as it's called, .returnsSequence is the right choice.

Every time your stub is called, it will return the next value in the sequence table. One cool trick is to include gaps in your sequence table. So, for example, if you wanted to return "" for every call except the 6th one, you could do:

stub( net, "ReadString" ).returnsSequence( { [6] = "hello" }, "" )

This would make net.ReadString return "" for the first 5 calls, "hello" for the 6th, and "" for every call after.

Note: Because lua discards all indices with nil values, using the default parameter will override any intentional nils in your sequence table.

The test is otherwise completely normal, but it's your job to tell GLuaTest when the test is done by calling done() or fail() anywhere in your test.

If your test fails for some reason before it can call done(), it'll be marked as having failed after timing out.

If you know the maximum amount of time your test will take, you can include the timeout key on the test with the number of seconds to wait until failing the test.

If you don't include a timeout on your Test Case, you'll have to wait for the default 60-second timer before the test can complete. So if speed is important to you, consider setting a conservative timeout value for your async tests.

For example, say we were trying to test this code:

-- lua/my_project/main.lua

MyProject = { didRun = false }

function MyProject:StartRun()
    timer.Simple( 2, function()
        MyProject.didRun = true
    end )
end

We want to make sure that when MyProject:StartRun() is called, that it changes MyProject.didRun two seconds later.

Our test might look like:

-- lua/tests/my_project/start_run.lua

return {
    groupName = "StartRun",
    cases = {
        {
            name = "Runs within two seconds of being called",
            async = true,
            timeout = 3, -- If it hasn't finished in 3 seconds, something went wrong and it can be marked as failed
            func = function()
                MyProject:StartRun()

                timer.Simple( 2, function()
                    expect( MyProject.didRun ).to.beTrue()
                    done()
                end )
            end
        }
    }
}

In the event that you want to fail a test manually, you can call fail( "with a reason if you want to" ) anywhere in your test case.

This is useful if you have a callback/timer/etc that should never run, and indeed, fail your test if it does.

Here's an example:

-- lua/tests/my_project/async_failure.lua

return {
    groupName = "Async Failure Examples",
    cases = {
        {
            name = "HTTP Request succeeds",
            async = true,
            timeout = 5,
            func = function()
                local success = function( body )
                    -- Expect exactly 1024 bytes in the body (for example)
                    expect( #body ).to.equal( 1024 )
                    done()
                end

                local failure = function( reason )
                    -- This shouldn't ever happen! If it does, we need to fail the test instead of letting it time out.
                    fail( "HTTP Request failed with reason: " .. reason )

                    -- We don't need to call done() here because we already called fail() :)
                end

                http.Fetch( "my url", success, failure )
            end
        }
    }
}

Here's an example of how beforeEach and afterEach could make your life easier while working with entities:

-- lua/tests/my_project/tickle_monster.lua

return {
    groupName = "Tickle Monster",

    beforeEach = function( state )
        state.ent = ents.Create( "sent_ticklemonster" )
        state.ent:Spawn()
    end,

    afterEach = function( state )
        if IsValid( state.ent ) then
            state.ent:Remove()
        end
    end,

    cases = {
        {
            name = "Should accept the Tickle function",
            func = function( state )
                expect( state.ent.Tickle ).to.exist()
                expect( function() state.ent:Tickle() end ).to.succeed()
                expect( state.ent.wasTickled ).to.beTrue()
            end
        },
        {
            name = "Should not be tickled by default",
            func = function( state )
                expect( state.ent.wasTickled ).to.beFalse()
            end
        },
        {
            name = "Should have the correct model",
            func = function( state )
                expect( state.ent:GetModel() ).to.equal( "materials/ticklemonster/default.mdl" )
            end
        }
    }
}

The beforeEach function created a brand-new Tickle Monster before every test, and the afterEach function deleted it, ensuring a clean test environment for each Test Case.

You'll notice the state variable in that example. The state parameter is just a table that's shared between the before/after funcs and the Test Case function.

You also have access to beforeAll and afterAll, which are self-explanatory. Please note that these two functions do not take a state table.

The cleanup function is a lot like afterEach, except it's used only for a specific Test Case.

One common way to use this is to make sure that your test cleans up after itself even if it errors.

For example, say I want to test my WrapperFunc in this file:

-- lua/my_project/wrapper.lua

GlobalFunc = function()
    return "Test"
end

WrapperFunc = function()
    return GlobalFunc()
end

I might write something like this:

{
    name = "Wrapper should call the original function",
    func = function()
        local ogGlobalFunc = GlobalFunc
        local wasCalled = false

        GlobalFunc = function()
            wasCalled = true
        end

        WrapperFunc()

        expect( wasCalled ).to.beTrue()

        GlobalFunc = ogGlobalFunc
    end
}

But consider, what would happen if WrapperFunc errored, or the expectation failed?

GlobalFunc would still be defined as our local function for all future tests, potentially causing them to fail.

Instead, we can use GLuaTest's cleanup function to make our test safer:

-- lua/tests/my_project/wrapper.lua

return {
    groupName = "Wrapper Functions",
    cases = {
        {
            name = "Wrapper should call the original function",

            func = function( state )
                state.GlobalFunc = GlobalFunc
                local wasCalled = false

                GlobalFunc = function()
                    wasCalled = true
                end

                WrapperFunc()

                expect( wasCalled ).to.beTrue()
            end,

            cleanup = function( state )
                GlobalFunc = state.GlobalFunc
            end
        }
    }

}

Try setting the gluatest_use_ansi convar to 0

Check out the wiki article outlining the hooks you can use: https://github.com/CFC-Servers/GLuaTest/wiki/Developers