Skip to content

Commit 91cf486

Browse files
elgopherelgopher
committedNov 28, 2024
Add a way to write custom assert functions
With this commit anyone can write custom assert functions and reuse them in multiple tests. Custom assert functions can call assert_*** or a new function called test_fail(). In order to properly print file and line number in the GUI, assert functions should call test_helper() function in the beginning.
·
0.5.10.5.0
1 parent c4d3254 commit 91cf486

File tree

5 files changed

+176
-94
lines changed

5 files changed

+176
-94
lines changed
 

‎README.md

+36
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@ Test API
4444
* [assert_not_close](#assert_not_close)
4545
* [assert_nil](#assert_nil)
4646
* [assert_not_nil](#assert_not_nil)
47+
* [test_helper](#test_helper)
48+
* [test_fail](#test_fail)
4749

4850
Introduction
4951
------------
@@ -142,6 +144,40 @@ Asserts that `actual` is not `nil`.
142144

143145
[Back to TOC](#test-api)
144146

147+
test_helper
148+
-----------
149+
150+
**syntax:** *test_helper()*
151+
152+
`test_helper` marks the calling function as a test helper function.
153+
When printing file and line information in GUI, that function will be
154+
skipped.
155+
156+
[Back to TOC](#test-api)
157+
158+
test_fail
159+
---------
160+
161+
**syntax:** *test_fail(err)*
162+
163+
Generates test error which stops current test execution and shows error to
164+
the user. In the GUI, the error will be presented together with a file name
165+
and line number where the `test_fail` function was executed. If you run
166+
`test_fail` from your own assert function, and want to see a place where this
167+
assert function was executed instead, please run the [test_helper()](#test_helper) function in the beginning of your assert function:
168+
```lua
169+
function custom_assert(....)
170+
test_helper() -- mark custom_assert function as test helper
171+
if .... then
172+
test_fail("message")
173+
end
174+
end
175+
```
176+
177+
`err` is an error message as a string or a table. All table fields will be presented in the GUI. Table could contain special `msg` field which will always be presented first.
178+
179+
[Back to TOC](#test-api)
180+
145181
Development - how to work on unitron
146182
====================================
147183

‎api.lua

+40-54
Original file line numberDiff line numberDiff line change
@@ -75,14 +75,6 @@ local function equal(expected, actual, visited_values)
7575
return expected == actual
7676
end
7777

78-
local function get_caller()
79-
local traceback = debug.traceback("", 3)
80-
local loc = split(traceback, "\n")[3]
81-
loc = string.gsub(loc, "(%d+):.*", "%1") -- drop message
82-
loc = string.gsub(loc, "\t", "") -- drop tabulator
83-
return loc
84-
end
85-
8678
local function serialize_arg(v)
8779
if v == nil then
8880
return nil
@@ -99,11 +91,10 @@ local function serialize_arg(v)
9991
return serialized:gsub("\\093", "]") -- TODO unescape all special characters
10092
end
10193

102-
local function serialize_message(msg)
94+
local function msg_or(msg, default)
10395
if msg == nil then
104-
return nil
96+
return default
10597
end
106-
10798
return tostring(msg)
10899
end
109100

@@ -121,32 +112,31 @@ end
121112
---
122113
---@param expected any
123114
---@param actual any
124-
---@param msg? any message which will be presented in the unitron ui.
115+
---@param msg? any message which will be presented in the unitron ui, instead of standard message
125116
function assert_eq(expected, actual, msg)
117+
test_helper()
118+
126119
if not equal(expected, actual) then
127-
local err = {
128-
assert = "eq",
129-
expected = serialize_arg(expected),
130-
actual = serialize_arg(actual),
131-
msg = serialize_message(msg),
132-
file = get_caller(),
120+
test_fail {
121+
msg = msg_or(msg, "args not equal"),
122+
expect = serialize_arg(expected),
123+
actual = serialize_arg(actual)
133124
}
134-
error(err)
135125
end
136126
end
137127

138128
---@param not_expected any
139129
---@param actual any
140-
---@param msg? any message which will be presented in the unitron ui.
130+
---@param msg? any message which will be presented in the unitron ui, instead of standard message
141131
function assert_not_eq(not_expected, actual, msg)
132+
test_helper()
133+
142134
if equal(not_expected, actual) then
143-
local err = {
144-
assert = "not_eq",
135+
test_fail {
136+
msg = msg_or(msg, "args are equal"),
137+
not_expect = serialize_arg(not_expected),
145138
actual = serialize_arg(actual),
146-
msg = serialize_message(msg),
147-
file = get_caller(),
148139
}
149-
error(err)
150140
end
151141
end
152142

@@ -163,64 +153,60 @@ end
163153
---@param expected number
164154
---@param actual number
165155
---@param delta number
166-
---@param msg? any message which will be presented in the unitron ui.
156+
---@param msg? any message which will be presented in the unitron ui, instead of standard message
167157
function assert_close(expected, actual, delta, msg)
158+
test_helper()
159+
168160
local invalid_args = expected == nil or actual == nil or delta == nil
169161
if invalid_args or abs(expected - actual) > delta then
170-
local err = {
171-
assert = "close",
172-
expected = as_string(expected), -- TODO Picotron has a bug that small numbers are not properly serialized
162+
test_fail {
163+
msg = msg_or(msg, "args not close"),
164+
expect = as_string(expected), -- TODO Picotron has a bug that small numbers are not properly serialized
173165
actual = as_string(actual), -- TODO Picotron has a bug that small numbers are not properly serialized
174166
delta = as_string(delta), -- TODO Picotron has a bug that small numbers are not properly serialized
175-
msg = serialize_message(msg),
176-
file = get_caller(),
177167
}
178-
error(err)
179168
end
180169
end
181170

182171
---@param not_expected number
183172
---@param actual number
184173
---@param delta number
185-
---@param msg? any message which will be presented in the unitron ui.
174+
---@param msg? any message which will be presented in the unitron ui, instead of standard message
186175
function assert_not_close(not_expected, actual, delta, msg)
176+
test_helper()
177+
187178
local invalid_args = not_expected == nil or actual == nil or delta == nil
188179
if invalid_args or abs(not_expected - actual) <= delta then
189-
local err = {
190-
assert = "not_close",
191-
not_expected = as_string(not_expected), -- TODO Picotron has a bug that small numbers are not properly serialized
192-
actual = as_string(actual), -- TODO Picotron has a bug that small numbers are not properly serialized
193-
delta = as_string(delta), -- TODO Picotron has a bug that small numbers are not properly serialized
194-
msg = serialize_message(msg),
195-
file = get_caller(),
180+
test_fail {
181+
msg = msg_or(msg, "args too close"),
182+
not_expect = as_string(not_expected), -- TODO Picotron has a bug that small numbers are not properly serialized
183+
actual = as_string(actual), -- TODO Picotron has a bug that small numbers are not properly serialized
184+
delta = as_string(delta), -- TODO Picotron has a bug that small numbers are not properly serialized
196185
}
197-
error(err)
198186
end
199187
end
200188

201189
---@param actual any
202-
---@param msg? any message which will be presented in the unitron ui.
190+
---@param msg? any message which will be presented in the unitron ui, instead of standard message
203191
function assert_not_nil(actual, msg)
192+
test_helper()
193+
204194
if actual == nil then
205-
local err = {
206-
assert = "not_nil",
207-
msg = serialize_message(msg),
208-
file = get_caller(),
195+
test_fail {
196+
msg = msg_or(msg, "arg is nil")
209197
}
210-
error(err)
211198
end
212199
end
213200

214201
---@param actual any
215-
---@param msg? any message which will be presented in the unitron ui.
202+
---@param msg? any message which will be presented in the unitron ui, instead of standard message
216203
function assert_nil(actual, msg)
204+
test_helper()
205+
217206
if actual != nil then
218-
local err = {
219-
assert = "nil",
220-
actual = as_string(actual),
221-
msg = serialize_message(msg),
222-
file = get_caller(),
207+
test_fail {
208+
msg = msg_or(msg, "arg is not nil"),
209+
actual = as_string(actual)
223210
}
224-
error(err)
225211
end
226212
end

‎examples/subject_test.lua

+22
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,28 @@ test("table driven tests", function()
8888
end
8989
end)
9090

91+
-- you can write your own custom assert functions
92+
test("custom assert function", function()
93+
local function assert_even(n)
94+
-- test_helper() marks the assert_even function as a test helper function.
95+
-- When printing file and line information in GUI, this function will be
96+
-- skipped.
97+
test_helper()
98+
99+
if n % 2 != 0 then
100+
test_fail {
101+
-- msg will be presented in the GUI when assertion failed:
102+
msg = "arg is not even",
103+
-- you can add as many fields as you want. All will be presented
104+
-- in the GUI along with msg:
105+
actual = n
106+
}
107+
end
108+
end
109+
110+
assert_even(3) -- change to even number in order to remove assertion error
111+
end)
112+
91113
-- test can be slow, but don't worry - it does not block the unitron ui
92114
test("slow test", function()
93115
for i = 1, 1000000 do

‎gui/gui.lua

+16-33
Original file line numberDiff line numberDiff line change
@@ -211,46 +211,29 @@ on_event("test_finished", function(e)
211211
message = "\fbTest successful"
212212
color = "\fb"
213213
else
214-
if err.file != nil then
215-
print_line(e.test, "\f8Error \f7at " .. err.file)
214+
if err.__traceback != nil and #err.__traceback > 0 then
215+
local file = err.__traceback[1]
216+
print_line(e.test, "\f8Error \f7at " .. file)
216217

217218
-- print additional message provided by user
218219
if err.msg != nil then
219220
print_line(e.test, err.msg)
220221
end
221222

222-
if err.assert == "eq" then
223-
print_line(e.test, "args not equal:")
224-
print_line(e.test, "\f5 expect=\f6" .. tostring(err.expected))
225-
print_line(e.test, "\f5 actual=\f6" .. tostring(err.actual))
226-
elseif err.assert == "not_eq" then
227-
print_line(e.test, "args are equal:")
223+
-- always print expected first
224+
if err.expect != nil then
225+
print_line(e.test, "\f5 expect=\f6" .. tostring(err.expect))
226+
end
227+
-- then actual
228+
if err.actual != nil then
228229
print_line(e.test, "\f5 actual=\f6" .. tostring(err.actual))
229-
elseif err.assert == "same" then
230-
print_line(e.test, "args are not the same:")
231-
print_line(e.test, "\f5 expect=\f6" .. err.expected)
232-
print_line(e.test, "\f5 actual=\f6" .. err.actual)
233-
elseif err.assert == "not_same" then
234-
print_line(e.test, "args are the same:")
235-
print_line(e.test, "\f5 actual=\f6" .. err.actual)
236-
elseif err.assert == "close" then
237-
print_line(e.test, "args not close")
238-
print_line(e.test, "\f5 expect=\f6" .. err.expected)
239-
print_line(e.test, "\f5 actual=\f6" .. err.actual)
240-
print_line(e.test, "\f5 delta =\f6" .. err.delta)
241-
elseif err.assert == "not_close" then
242-
print_line(e.test, "args too close")
243-
print_line(e.test, "\f5 not_ex=\f6" .. err.not_expected)
244-
print_line(e.test, "\f5 actual=\f6" .. err.actual)
245-
print_line(e.test, "\f5 delta =\f6" .. err.delta)
246-
elseif err.assert == "not_nil" then
247-
print_line(e.test, "arg is nil")
248-
elseif err.assert == "nil" then
249-
print_line(e.test, err.actual .. " is not nil")
250-
elseif err.assert == "true" then
251-
print_line(e.test, "arg is false")
252-
elseif err.assert == "false" then
253-
print_line(e.test, "arg is true")
230+
end
231+
232+
-- TODO sort alphabetically?
233+
for k, v in pairs(err) do
234+
if k != "msg" and k != "expect" and k != "actual" and k != "__traceback" then
235+
print_line(e.test, "\f5 " .. k .. "=\f6" .. tostring(v))
236+
end
254237
end
255238
end
256239

‎runner.lua

+62-7
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ local tests <const> = {} -- {id=1,name=..}
2929

3030
local publish_throttler <const> = new_throttler(50) -- max 50 messages per frame
3131

32+
-- key is a file:linedefined, value is always true:
33+
local helpers <const> = {}
34+
3235
local function publish(msg)
3336
publish_throttler:throttle()
3437
send_message(parent_pid, msg)
@@ -64,16 +67,17 @@ function test(name, test)
6467
if not success then
6568
if type(err) == "string" then
6669
local escaped_work_dir = work_dir:gsub("([%W])", "%%%1")
67-
local file = ""
70+
-- file locator is file path with line no, eg. "/workdir/file.lua:10: "
71+
local file_locator_pattern = escaped_work_dir .. "[^ ]+:%d+: "
6872
local msg = err
69-
if string.match(err, escaped_work_dir) then
70-
file = string.gsub(err, "(%d+):.*", "%1") -- drop message
71-
msg = string.gsub(err, file .. ": ", "")
73+
74+
local file = string.match(err, file_locator_pattern)
75+
if file then
76+
msg = err:sub(#file + 1, #err)
77+
file = file:sub(1, #file - 2) -- drop ": "
7278
end
7379
err = {
74-
assert = "generic",
75-
original_error = err,
76-
file = file,
80+
__traceback = { file },
7781
msg = msg,
7882
}
7983
end
@@ -90,6 +94,57 @@ function test(name, test)
9094
publish { event = "test_finished", test = current_test, error = err }
9195
end
9296

97+
-- test_helper marks the calling function as a test helper function.
98+
-- When printing file and line information in GUI, that function will be
99+
-- skipped.
100+
function test_helper()
101+
local info = debug.getinfo(2, "Sl")
102+
local info_string = string.format("%s:%d", info.short_src, info.linedefined)
103+
helpers[info_string] = true
104+
end
105+
106+
---Generates stack traceback (skipping helpers)
107+
---@return table
108+
local function traceback()
109+
local trace = {}
110+
111+
for level = 3, math.huge do
112+
local info = debug.getinfo(level, "Sl")
113+
if info == nil then break end
114+
local info_string = string.format("%s:%d", info.short_src, info.linedefined)
115+
if not helpers[info_string] then
116+
table.insert(trace, string.format("%s:%d", info.short_src, info.currentline))
117+
end
118+
end
119+
120+
return trace
121+
end
122+
123+
---Generates test error which stops current test execution and shows error to
124+
---the user. In the GUI, the error will be presented together with a file name
125+
---and line number where the `test_fail` function was executed. If you run
126+
---`test_fail` from your own assert function, and want to see a place where this
127+
---assert function was executed instead, please run the test_helper() function
128+
---in the beginning of your assert function:
129+
---```
130+
--- function custom_assert(....)
131+
--- test_helper() -- mark custom_assert function as test helper
132+
--- if .... then
133+
--- test_fail("message")
134+
--- end
135+
--- end
136+
---```
137+
---@param err string|table Error message as a string or a table. All table fields will be presented in the GUI. Table could contain special `msg` field which will always be presented first.
138+
function test_fail(err)
139+
if type(err) != "table" then
140+
err = { msg = tostring(err) }
141+
end
142+
143+
err.__traceback = traceback()
144+
145+
error(err)
146+
end
147+
93148
local originalPrint <const> = print
94149

95150
-- override picotron print, so all text is sent to the parent process

0 commit comments

Comments
 (0)
Please sign in to comment.