TestLib

Working on a large library can easily become a nightmare to maintain. One minor change in a class can have huge, cascading effects, or maybe just break one hidden little feature you rarely test.

This library attempts to help with this challenge by allowing you to easily create and run unit tests against your class methods.

TestLib includes a set of opinionated defaults that should be sufficient for many use cases, but it is also highly extensible and modular.

Best Practices for Testing

For the smoothest experience, I recommend the following practices be used within your app:

1. Save all of the classes you're testing in a file named after the class, for example ClassName.ahk.
2. Save each of your test classes right next to the class you're testing with the same name and the .test.ahk extension, for example ClassName.test.ahk

This will mean that TestLib's default functionality will be able to inspect your classes and find your tests. Other structures will require more configuration of TestLib, as well as possibly extending some classes.

Setup Guide

1. Start by downloading the latest version of TestLib to a subdirectory of your AHKv2 project.

2. Create a file (ideally in the top directory of your AHK application) to run your tests.

Here is an example test script derived from my Launchpad application, named LaunchpadTest.ahk:

#Warn

#Include Lib\Includes.ahk
#Include TestLib\Includes.ahk
#Include Lib\Includes.test.ahk

HtmlResultViewer()
    .SetTitle("Launchpad Test")
    .ViewResults(SimpleTestRunner(FilesystemTestLoader().GetTests()).RunTests())

Let's break that down:

• TestLib\Includes.ahk is the Includes.ahk file that comes with TestLib, and you should always include it at the top of your test script.
• Lib\Includes.ahk is how I load all available classes in my application. You can do this any way you want, but the important thing is that all classes you're testing are available.
• Lib\Includes.test.ahk is a file generated by TestLib's include generator script. We'll cover that later, but for now just know the test includes needs to be loaded here.
• HtmlResultViewer displays test results as webpage in a simple GUI window
• SimpleTestRunner simply takes an array of tests and runs them in sequence
• FilesystemTestLoader automatically loads all of your tests by looking for files using the ClassName.test.ahk pattern

3. Create your test classes, which should be derived from TestBase.

Here's an example test class for a class called Debugger, named Debugger.test.ahk:

class DebuggerTest extends TestBase {
    debuggerInstance := ""

    CreateTestInstances() {
        this.debuggerInstance := Debugger()
    }

    TestToString() {
        testStrings := [
            "Test string 1",
            "Another test string"
        ]
        
        for testString in testStrings {
            this.AssertEquals(
                "`"" . testString . "`"",
                this.debuggerInstance.ToString(testString),
                "Passing a string wraps it in quotes"
            )

            this.AssertEquals(
                "`"" . testString . "`"",
                this.debuggerInstance.ToString("`"" . testString . "`""),
                "Passing a quoted string returns the same string"
            )
        }
        
        
    }

    TestGetIndent() {
        indents := Map(
            0, "",
            5, "-----",
            10, "----------"
        )

        indentStr := "-"

        for level, matchStr in indents {
            this.AssertEquals(
                this.debuggerInstance.GetIndent(level, indentStr), 
                matchStr,
                "Level " . level . " returns the correct string"
            )
        }
    }
}

Name your test methods "Test[MethodName]" where [MethodName] is the name of the class method you're testing. This naming scheme is important, because it allows TestLib to find your test methods and automatically determine which class method they are testing.

TestBase offers numerous other built-in assertions beyond AssertEquals, and you can easily write any other custom assertion you want.

4. Create your Includes.test.ahk file after you write one or more test classes, and make sure it's included in your main test file like shown above.

5. Now, simply run your test script and wait for the results to open when complete.