Skip to content

Developers

Jump to bottom
Brandon Sturgeon edited this page Jan 2, 2023 · 11 revisions

Extensions

Are you interested in writing an extension for GLuaTest? That's great!

Please remember you can always reach out for help, even for simple questions.

GLuaTest exposes the following Hooks:


GLuaTest_CreateExpect

This hook is called when a new expect object is created.

You can modify the given table in any way you'd like, and it'll be exposed inside of the tests cases.

Parameters

  • subject: The subject of the expectation. (The value passed into expect( ) in the test case)
  • expect: The created expect table

Example

Let's use the CreateExpect hook to add a new expectation.

hook.Add( "GLuaTest_CreateExpect", "Add_GTE", function( subject, expect )
    local to = expect.to
    local expected = to.expected

    function to.beGreaterThanOrEqualTo( comparison )
        if subject < comparison then
            expected( "to be greater than or equal to '%s'", comparison )
        end
    end
end )

GLuaTest_RunTestFiles

This hook is called after the test files have been found, configured, and prepared. They will be run immediately after this hook.

Parameters

  • testFiles A sequential table of Test Files (description below)

A Test File looks like this:

Key Type Description
fileName string The test filename (not path)
groupName string The groupName key set in the test file (can be nil)
cases table A sequential table of test cases (the contents of the cases key in the test file)
project string The name of the directory under the tests/ directory that this test file is located

Example

In this example, we'll add a new feature that allows users to mark a test file as "skipped" and exclude it from being automatically run.

hook.Add( "GLuaTest_RunTestFiles", "Add_Skipped", function( testFiles )
    for i = #testFiles, 1, -1, do
        local testFile = testFiles[i]

        if testFile.skip == true then
            table.remove( testFiles, i )
        end
    end
end )

GLuaTest_MakeColors

This hook is called when the colors table is created for the result logger.

Parameters

  • colors: A table with color names as the keys, and Color objects as the value

Example

For this extension, we'll slightly tweak the default red color

hook.Add( "GLuaTest_MakeColors", "Change_RedColor", function( colors )
    colors.red = Color( 225, 75, 75 )
end )

GLuaTest_MakeLogHelpers

This hook is called when an instance of LogHelpers is created.

You can use this hook to stub, modify, or overwrite any of the methods in LogHelpers.

You can see the available methods in the LogHelpers file.

Parameters

  • LogHelpers: A table of Log Helper methods

GLuaTest_MakeResultLogger

This hook is called when a new instance of ResultLogger is created.

You can use this hook to stub, modify, or overwrite any of the methods in ResultLogger.

You can see the available methods in the ResultLogger file.

Parameters

  • ResultLogger: A table of Result Logger methods

GLuaTest_LogTestResult

This hook runs when a test case finishes, and is about to be logged.

You can use this hook to modify anything about the result before it's logged.

Parameters

  • result: A Result object (see below)

The Result object

Key Type Description
success boolean/nil A boolean indicating if the test case succeeded. If the test is empty, this field will be nil
testGroup table The TestGroup object for this test case
case table The TestCase object
errInfo table/nil A table containing information about the failure. If success is true, this field will be nil

GLuaTest_CanRunTestCase

This hook runs when GLuaTest is about to run a test case. You can use this hook to modify the test case, or to prevent the test case from being run.

Parameters

  • testGroup: The TestGroup object
  • case: The TestCase object

Returns

  • false to prevent the test case from running

GLuaTest_CreateStub

This hook runs when a new Stub object is created. This hook can be used to add or change a Stub's functionality.

Parameters

  • stubTbl: The Stub object
  • meta: The metatable that will be applied to the stubTbl
  • tbl: A reference to the table that is being modified with this Stub (can be nil)
  • key: The key of the tbl that is being modified with this Stub (can be nil)

GLuaTest_Finished

This hook runs after all test cases in all test groups are complete. In the Docker environment, the instance will exit 3 seconds after this hook fires.

Parameters

  • testGroups: All TestGroup objects that were processed in this test run
  • allResults: All TestResult objects that were produced in this test run
  • duration : The total time in seconds that the test run took to complete

A TestResult looks like this:

Key Type Description
success bool? Indicates if the test succeeded. nil if the test case did not fail or call an expectation
testGroup table The testGroup that this result was run from
case table The original TestCase defined in the test file
errInfo table? The ErrorInfo object produced from a failed test case. nil if the test case did not fail or call an expectation

An ErrorInfo looks like this:

Key Type Description
reason string The cleaned (i.e. no file name/line number) error reason
sourceFile string The path to the source file of the error
lineNumber string The line number of the error
locals table An aggregate of all locals (from debug.getlocal) at the time of the error
Clone this wiki locally