Test

Library

Updated 2 months ago · v1.3.7

Server & Client — write tests anywhere with lib.test.add, then run them from the server console with dirktest. It is console-only: a connected player can never trigger a test run.

lib.test is a lightweight, Jest-style test runner. It's ideal for validating bridges (inventory / framework / …) and any server logic with a single console command — including bridge-compat suites that stay green across ox / qb / qs / devix / bp / etc.

lib.test.add

Register a test. The callback runs inside a coroutine, so it can lib.callback.await(...), call lib.inventory / lib.player, and Wait() freely.

lua

lib.test.add(name, fn, opts)

Parameter	Type	Required	Description
name	string	true	Test name (also what the console filter matches)
fn	function	true	`function(ctx) ... end` — receives the test context
opts	table	false	`{ requiresPlayer, context, skip }` (see below)

opts

Key	Type	Description
requiresPlayer	boolean	Passes a connected player src as `ctx.player`; the test is skipped if no player is online
context	string	`'server'`, `'client'` or `'shared'` (default) — the test only runs in a matching context
skip	boolean	Reported as skipped

The test context (`ctx`)

Field	Description
`ctx.expect(v)`	Chainable matchers (below); each throws on failure
`ctx.player`	Target player src (server + requiresPlayer) or the local server id (client)
`ctx.fail(msg)`	Force-fail with a message

Matchers

lua

ctx.expect(x).toBe(y)               -- equality (==)
ctx.expect(x).toEqual(y)            -- deep equality (tables)
ctx.expect(x).toBeTruthy()
ctx.expect(x).toBeFalsy()
ctx.expect(x).toBeNil()
ctx.expect(x).notToBeNil()
ctx.expect(x).toBeType('table')
ctx.expect(x).toBeGreaterThan(n)
ctx.expect(x).toBeGreaterOrEqual(n)
ctx.expect(x).toContain(v)          -- table contains value

Running tests

From the server console only:

code

dirktest                 -- run everything
dirktest inventory       -- only tests whose name contains "inventory"
dirktest xp 2            -- "xp" tests against player id 2
dirktest * 2 +c          -- everything on player 2, incl. client-side tests

Arguments are [nameFilter] [playerId] [+c] in any order.

dirktest is console-only (guarded by source == 0) and registered as a restricted command — a player cannot run it whatever their permissions. requiresPlayer tests briefly mutate a player's inventory/data and restore afterwards, so run them on a test server, not a live one.

Example

lua

lib.test.add('inventory: add + remove roundtrip', function(t)
  local src = t.player
  local before = tonumber(lib.inventory.hasItem(src, 'water')) or 0

  lib.inventory.addItem(src, 'water', 2)
  Wait(200)
  t.expect((tonumber(lib.inventory.hasItem(src, 'water')) or 0) - before).toBe(2)

  lib.inventory.removeItem(src, 'water', 2)
end, { requiresPlayer = true })

Enabling it in your resource

The runner activates once lib.test is loaded. To guarantee it's available on both server and client (the client half powers the +c leg), declare it in your fxmanifest.lua:

lua

dirk_lib 'test'

server_script 'tests/server.lua'
client_script 'tests/client.lua'

Cross-context note: lib.test lazy-loads per context, so the server command and the client endpoint only register when lib.test is touched in each context. The dirk_lib 'test' manifest flag force-loads it in both — which is why it's the recommended setup rather than relying on a lazy touch.

Was this page helpful?

This page was last updated on 7 August 2026

← Previoustarget

Next →validate

Test

#lib.test.add

#The test context (ctx)

#Matchers

#Running tests

#Example