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 Runneron: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/ulxTeamUlysses/ulibCFC-Servers/gm_logger@lua

name:GLuaTest Runneron:pull_request:jobs:run-tests:uses:CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@mainwith:requirements:lua/tests/my_project/requirements.txt

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

name:GLuaTest Runneron:pull_request:jobs:run-tests:uses:CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@mainwith:server-cfg:lua/tests/my_project/server.cfg

name:GLuaTest Runneron:pull_request:jobs:run-tests:uses:CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@mainwith:gamemode:darkrpmap:rp_downtown_tits_v2

name:GLuaTest Runneron:pull_request:jobs:run-tests:uses:CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@mainwith:collection:1629732176

name:GLuaTest Runneron:pull_request:jobs:run-tests:uses:CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@mainwith:branch:x86-64

name:GLuaTest Runneron:pull_request:jobs:run-tests:uses:CFC-Servers/GLuaTest/.github/workflows/run_tests.yml@mainwith:extra-startup-args:"-tickrate 16 -usegh"

Running tests in a GitHub Runner is surprisingly fast.

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

In fact, the test suite itself will often complete in only a couple of seconds. Most of the time is spent downloading the image and setting up the runner.

(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 youraddons/ directory 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 theGitHub 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.txtexport CUSTOM_SERVER_CONFIG=/absolute/path/to/server.cfgexport PROJECT_DIR=/home/me/Code/my_projectexport GAMEMODE="sandbox"export COLLECTION_ID="12345"export SSH_PRIVATE_KEY="the-entire-private-key"export GITHUB_TOKEN="a-personal-access-token"

• You can skip theREQUIREMENTS andCUSTOM_SERVER_CONFIG if you don't need them, but you must set thePROJECT_DIR variable.

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

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

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

• TheGITHUB_TOKEN variable, like theSSH_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 thedocker-compose file in thedocker/ 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.

In these situations, you can use thecoroutine option to run your test in a coroutine.

For example, if you're testing with Nextbots, you'll find it frustrating to wait for them to disconnect before your next test runs.

-- lua/gluatest/extensions/my_nextbot_extensions.lua--- Halts the coroutine until the server is emptyWaitForEmptyServer=function()localco=coroutine.running()localidentifier=getWaitIdentifier()hook.Add("Think",identifier,function()localcount=player.GetCount()ifcount>0thenreturnendhook.Remove("Think",identifier )coroutine.resume(co )end )returncoroutine.yield()end

-- lua/tests/my_nextbot/my_nextbot.luareturn {groupName="My Nextbot tests",-- Automatically kick all bots after each testafterEach=function()for_,botinipairs(player.GetBots() )dogame.KickID(bot:UserID() )endend,cases= {        {name="Should be able to spawn a nextbot",async=true,timeout=2,coroutine=true,func=function()WaitForEmptyServer()-- We need to be sure the server is empty before we do our tests, otherwise it could fail due to timinglocalmyBot=player.CreateNextBot("Silly little guy")expect(player.GetCount() ).to.equal(1 )expect(player.GetAll()[1] ).to.equal(myBot )done()end        }    }}

Let's say your addon looks like this:

MyProject= {}functionMyProject.UserExistsInDatabase(user )localuserObject=lookupUserInDatabase(user )returnuserObject.existsendfunctionMyProject.CheckUser(user )ifnotMyProject.UserExistsInDatabase(user )thenreturnendifnotuser.namethenreturnendif#user.name==0thenreturnendreturntrueend

You want to test the functionality ofCheckUser.

There are three checks inCheckUser:

• 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 thedatabase, you're testingCheckUser.

Instead, we couldpretend thatUserExistsInDatabase returnstrue for our tests. We can do this using a Stub.

-- lua/tests/my_project/checkuser.luareturn {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()localdbCheck=stub(MyProject,"UserExistsInDatabase").returns(true )MyProject.CheckUser(state.validUser )expect(dbCheck ).to.haveBeenCalled()end        }    }}

Now ourCheckUser testonly tests the functionality inCheckUser, 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 usestub: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 callingstub() 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()localmyStub=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 makenet.ReadString return"" for the first 5 calls,"hello" for the 6th, and"" for every call after.

Note: Because lua discards all indices withnil values, using thedefault parameter will override any intentionalnils in your sequence table.

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

If your test fails for some reason before it can calldone(), 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 thetimeout key on the test with the number of seconds to wait until failing the test.

If you don't include atimeout 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 conservativetimeout value for your async tests.

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

-- lua/my_project/main.luaMyProject= {didRun=false }functionMyProject:StartRun()timer.Simple(2,function()MyProject.didRun=trueend )end

We want to make sure that whenMyProject:StartRun() is called, that it changesMyProject.didRun two seconds later.

Our test might look like:

-- lua/tests/my_project/start_run.luareturn {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 failedfunc=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 callfail( "with a reason if you want to" ) anywhere in your test case.

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

Here's an example:

-- lua/tests/my_project/async_failure.luareturn {groupName="Async Failure Examples",cases= {        {name="HTTP Request succeeds",async=true,timeout=5,func=function()localsuccess=function(body )-- Expect exactly 1024 bytes in the body (for example)expect(#body ).to.equal(1024 )done()endlocalfailure=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() :)endhttp.Fetch("my url",success,failure )end        }    }}

Here's an example of howbeforeEach andafterEach could make your life easier while working with entities:

-- lua/tests/my_project/tickle_monster.luareturn {groupName="Tickle Monster",beforeEach=function(state )state.ent=ents.Create("sent_ticklemonster")state.ent:Spawn()end,afterEach=function(state )ifIsValid(state.ent )thenstate.ent:Remove()endend,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        }    }}

ThebeforeEach function created a brand-new Tickle Monster before every test, and theafterEach function deleted it, ensuring a clean test environment for each Test Case.

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

You also have access tobeforeAll andafterAll, which are self-explanatory. Please note that these two functionsdo not take astate table.

Thecleanup function is a lot likeafterEach, 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 myWrapperFunc in this file:

-- lua/my_project/wrapper.luaGlobalFunc=function()return"Test"endWrapperFunc=function()returnGlobalFunc()end

I might write something like this:

{name="Wrapper should call the original function",func=function()localogGlobalFunc=GlobalFunclocalwasCalled=falseGlobalFunc=function()wasCalled=trueendWrapperFunc()expect(wasCalled ).to.beTrue()GlobalFunc=ogGlobalFuncend}

But consider, what would happen ifWrapperFunc 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'scleanup function to make our test safer:

-- lua/tests/my_project/wrapper.luareturn {groupName="Wrapper Functions",cases= {        {name="Wrapper should call the original function",func=function(state )state.GlobalFunc=GlobalFunclocalwasCalled=falseGlobalFunc=function()wasCalled=trueendWrapperFunc()expect(wasCalled ).to.beTrue()end,cleanup=function(state )GlobalFunc=state.GlobalFuncend        }    }}

If you have a function or tool that you'd like to use in your tests, you can add it to thegluatest/extensions/ directory.

For example, if you were going to be testing a lot of entities in the same way, you could save yourself some headache by making an extension like this:

-- lua/gluatest/extensions/with_entity.lua--- Returns a GLuaTest TestGroup that is set up for Entity Testing--- @paramclassnamestring The class name of the entity to spawn--- @paramtestGroupGLuaTest_TestGroupWithEntityTests=function(classname,testGroup )testGroup.beforeEach=function(state )state.ents= {}functionstate.SpawnEnt()localent=ents.Create(classname )ent:Spawn()table.insert(state.ents,ent )returnentendfunctionstate.RemoveEnt(ent )table.RemoveByValue(state.ents,ent )ifIsValid(ent )thenent:Remove()endendendtestGroup.afterEach=function(state )for_,entinipairs(state.ents )doifIsValid(ent )thenent:Remove()endendendend

And then you can set up your test like this:

-- lua/tests/my_project/entity_1.luareturnWithEntityTests("my_special_entity", {groupName="My Special Entity Tests",-- No need to include any special setup/cleanup logic here as it's already handled by WithEntityTestscases= {        {name="Spawns with default values",func=function(state )localent=state.SpawnEnt()expect(ent:GetModel() ).to.equal("models/my_special_entity.mdl")expect(ent:GetColor() ).to.equal(Color(255,255,255 ) )end        }    }} )

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