Writing Tests

1. Create a Tests Folder

First, create a folder named tests in your project directory. This folder will contain all your test files.

mkdir tests

2. Create Test Files

Inside the tests folder, create a Lua file for each set of tests you want to write. Ensure that each test file has a filename prefix of test so that Leste can discover and execute them. For example, testExample.lua.

3. Write Test Cases

In each test file, you can define multiple test cases using the Leste.it function. Each test case consists of a description and a function containing the test assertions.

Here's an example of a valid test file (testExample.lua):

local Leste = require("leste.leste")

-- Test case 1: A basic example
Leste.it("Remember to write an interesting and well-explained description about the test.", function()
    assert(true)
end)

-- Test case 2: Using print statements for debugging
Leste.it("You can add print statements if you need to debug, but remember to use the -v flag.", function()
    print("This message will appear in the test standard output.")
    assert(true)
end)

Tip

Utilizing Lua's assert function is an effective method for asserting your tests. For more detailed output, consider utilizing the leste.assertions module — it offers a range of assert functions that are adept at handling errors more efficiently.

4. Test Hooks

Leste supports four hook functions to run code around your tests: Leste.beforeAll, Leste.afterAll, Leste.beforeEach and Leste.afterEach. They're useful for setup and teardown logic, such as preparing shared state or cleaning up after tests.

• Leste.beforeAll(fn): Runs fn once, before any test in the file runs.
• Leste.afterAll(fn): Runs fn once, after every test in the file has finished.
• Leste.beforeEach(fn): Runs fn before each individual test.
• Leste.afterEach(fn): Runs fn after each individual test.

local Leste = require("leste.leste")

local database = nil

Leste.beforeAll(function()
    database = { users = {} }
end)

Leste.beforeEach(function()
    database.users = {}
end)

Leste.it("adds a user to an empty database", function()
    table.insert(database.users, "Ada")
    assert(#database.users == 1)
end)

Leste.it("starts with an empty user list on every test", function()
    -- beforeEach already reset database.users, regardless of test order
    assert(#database.users == 0)
end)

Leste.afterAll(function()
    database = nil
end)

5. Using the Assertions Module

While Lua's built-in assert works fine for simple checks, the leste.assertions module provides ready-made assertions with clearer default failure messages. See the Assertions Reference for the full list.

local Leste = require("leste.leste")
local Assertions = require("leste.assertions")

Leste.it("demonstrates the Assertions module", function()
    Assertions.assert(1 + 1 == 2)
    Assertions.equal(2, 1 + 1)
    Assertions.strContains("Hello, World!", "World")

    local user = { name = "Ada", age = 36 }
    Assertions.tableHasKey(user, "name")
    Assertions.tableContains(user, "Ada")
end)

6. Run Tests

To execute the tests, use the Leste CLI interface. Navigate to your project directory in the terminal and run:

leste -v

This command will automatically run all the test files (test*) located in the tests folder. You can also specify a specific folder to run tests from if needed.

Try running the same command without -v to see how the print/io.write output is silenced.

leste

Example Test Execution

After running the tests, you will see the test results displayed in the terminal, including passed and failed tests, execution time, and any assertion errors, general errors, or debug output.

    PASS   Remember to write an interesting and well-explained description about the test.

    File:    testExample.lua
    Time:    0.00s
    Asserts: .

    PASS   You can add print statements if you need to debug, but remember to use the -v flag.

    File:    testExample.lua
    Time:    0.00s
    Asserts: .

STDOUT:
This message will appear in the test standard output.


    ✓ All tests passed successfully

    Tests:      2 tests    2 passed    0 failed    (2 assertions)
    Duration:   0.00s