GLuaTest

🎉 The missing test framework for GMod 🎉

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 (albeit strange) 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)

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

Handsome, informative error reporting

Some additional reading:

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.

Automated testing on Pull Requests

Running locally

Running locally without a server

Writing Tests ✍️

Your first test file

In your GLua project, create a new directory: lua/tests/<your project name>/.

This is where you'll keep the tests for your project. You can put all of your tests in one file, or split the files up based on module/responsibility.

For example, if your addon had two entities you'd like to test, you could make lua/tests/your_project/entity_1.lua and lua/tests/your_project/entity_2.lua. We suggest you group your tests, but it'll work either way.

The test file itself is fairly simple. It has a few keys you can use, but the only requirement is the cases key; a table of Test Cases.

For example:

-- lua/tests/my_clock/get_time.lua

return {
    cases = {
        {
            name = "It should return the correct time",
            func = function()
                local myClock = Clock.New()
                local realTime = os.time()

                expect( myClock:GetTime() ).to.equal( realTime )
            end
        }
    }
}

The Test Group

The Test Case

Each Test Case is a table with the following keys:

The expect function

The heart of a test is the expectation. You did a thing, and now you expect a result.

In each test function, you have access to the expect function.

Let's say you expect "a" to equal "b". In regular Lua you might do:

assert( "a" == "b" )

Similarly, in GLuaTest, you'd do:

expect( "a" ).to.equal( "b" )

There are a number of different expectations you can use.

Expectations

Expectation Negation

You can invert an Expectation by using .toNot or .notTo in place of your .to

i.e.:

expect( ply ).toNot.beInvalid()
expect( "test" ).notTo.beA( "table" )

Was

You may replace .to with .was in any expectation. .wasNot is also valid.

Primarily this is syntax sugar for the called expectation. Technically these two calls are equivalent:

expect( func ).to.called()
expect( func ).was.called()

when and skip

These fields can be used to control your test invocation.

For example, to run your test case only on the x86-64 branch:

{
    name = "Is valid on x86-64",
    when = BRANCH == "x86-64",
    func = function()
        -- x86-64 specific stuff here
    end
}

Skipping is also handy if you want to disable a test but keep the code:

{
    name = "Broken test (but I'll definitely fix it some day 100%),
    skip = true,
    func = function() error() end
}

Note: skip takes precedence over when

The stub function

Async tests and the done/fail functions

Before / After functions

You may find yourself writing a lot of repetitive setup/teardown code in each of your Test Cases.

Now what?

At this point, you might be excited to try GLuaTest. Maybe you already have a test file set up!

But... now what?

Check out this wiki page addressing that very question:

https://github.com/CFC-Servers/GLuaTest/wiki/I-set-up-GLuaTest...-now-what

Troubleshooting 🤔

Developers 👨‍💻