Tests (spec)

The Test Artifact (spec)

Filetype:{filename}.e.spec.lua or {filename}.mh.spec.lua

A spec is a TENUM® artifact used to define automated tests for other artifacts—like entities or message handlers. Whenever you update a spec file or the artifact it covers, TENUM® automatically runs these tests and reports any failures.

Usage Sample

Specs are TENUM® ’s automated test artifacts. Whenever you create a file named something.e.spec.lua (for an entity) or something.mh.spec.lua (for a message handler), TENUM®'s built in runner automatically notices it and runs the tests whenever either the spec file or the artifact are executed.

This gives you a quick feedback loop to ensure your commands, events, and queries behave as expected—without needing to set up an external test framework.

Let’s say you want to confirm that your “create” command really does create new to-dos correctly. That’s a great use case for a spec artifact. Here’s a quick example:

Sample App: **TENUM®** ToDo App

Sample Module: todo.e.spec.lua

local export = {}
local todo = require("todo.api.todo")
local todoList = require("todo.api.todoList")

function export.testCreateTodo()
  todoList.commands.create{ id = "mylist" }
  local todoId = todo.commands.create{ title = "Test Todo", listId = "mylist" }
  local entity = todo.queries.getTodo{ id = todoId }
  assert(entity and entity.title == "Test Todo", "Todo should be created with given title")
  assert(entity.completed == false, "New todo should not be completed")
end

function export.testToggleTodo()
  todoList.commands.create{ id = "mylist" }
  local todoId = "generated_todo_id"
  todo.commands.create{ id = todoId, title = "Test Toggle", listId = "mylist" }
  todo.commands.toggleComplete{ id = todoId }
  local entity = todo.queries.getTodo{ id = todoId }
  assert(entity.completed == true, "Todo should be toggled to completed")
end

return export

Bestb Practices

Test Small, Isolated Units
- Write tests that cover individual commands, queries, and events to ensure each part of your logic behaves correctly in isolation.
Use Clear Assertions
- Make assertions specific and clear to easily identify what went wrong when a test fails.
Cover Edge Cases
- Include tests for edge cases, such as invalid input, missing data, and concurrent operations, to ensure robustness.
Automate Regularly
- Take advantage of TENUM® ’s automatic test execution by creating spec files that align with your artifacts, ensuring tests run with every code change.
Mock External Dependencies
- Where necessary, mock external APIs or modules to keep tests focused on your logic without relying on external systems.

Last modified: 11 April 2025