rayvn/test

Test assertions.

Assert Functions

assertNotInFile()

Fail if a pattern is found in a file.

args

match (string)	Pattern to search for.
file (string)	Path to the file to search.

assertInFile()

Fail if a grep pattern is not found in a file.

args

match (string)	Pattern to search for.
file (string)	Path to the file to search.

assertEqual()

Fails with a message if two strings are not equal.

args

expected (string)	Expected value.
actual (string)	Actual value.
message (string)	Optional custom failure message.

assertNotEqual()

Fails with a message if two strings are equal.

args

unexpected (string)	Value that actual should not equal.
actual (string)	Actual value.
message (string)	Optional custom failure message.

assertEqualStripped()

Fail if expected does not equal actual after stripping ANSI escape codes from actual.

args

expected (string)	Expected plain-text value.
actual (string)	Value to compare; ANSI codes are stripped before comparison.
msg (string)	Optional failure message.

assertEqualEscapeCodes()

Assert two strings are equal, printing both with cat -v (escape codes visible) on failure.

args

expected (string)	Expected value (may contain escape codes).
actual (string)	Actual value to compare.
msg (string)	Failure message; defaults to “assertEqualEscapeCodes failed”.

assertTrue()

Fail with msg if a command exits non-zero.

args

msg (string)	Failure message to display.
@	Command and arguments to execute.

assertFalse()

Fail with msg if a command exits zero.

args

msg (string)	Message to display on failure.
cmd (string)	Command and arguments to execute.

assertContains()

Fail if actual does not contain expected as a substring.

args

expected (string)	Substring that must be present in actual.
actual (string)	Value to search within.
msg (string)	Optional custom failure message.

assertInRange()

Fail if a numeric value is not within the inclusive range [min, max].

args

value (int)	Value to check.
min (int)	Minimum allowed value (inclusive).
max (int)	Maximum allowed value (inclusive).
msg (string)	Custom failure message.

assertEqualIgnoreCase()

Fail if two strings are not equal, ignoring case.

assertNotInPath()

Fails if an executable is found in PATH.

assertInPath()

Fail if an executable is not found in PATH, or optionally at an unexpected path.

args

executable (string)	Name of the command that must be in PATH.
expectedPath (string)	Expected path; checked against both the found path and its

assertFunctionIsNotDefined()

Fail if a function with the given name is currently defined.

args

name (string)	Name of the function that must not be defined.

assertVarIsNotDefined()

Fail if a variable with the given name is currently defined.

args

name (string)	Variable name that must not be defined.

assertFunctionIsDefined()

Fail if a function with the given name is not currently defined.

args

name (string)	Name of the function that must be defined.

assertVarIsDefined()

Fail if a variable with the given name is not currently defined.

args

name (string)	Name of the variable to check.

assertVarType()

Fail if a variable’s declare flags do not match the expected set (order-independent).

args

varName (stringRef)	Name of the variable to inspect.
expectedFlags (string)	Expected declare flags as a string (e.g. “ir”, “r”, “arx”, “A”).

assertVarEquals()

Fail if a named variable’s value does not equal the expected string.

args

varName (stringRef)	The name of the variable to check.
expected (string)	The expected string value.

assertVarContains()

Fail if the variable named varName does not contain expected as a substring.

args

varName (stringRef)	Name of the variable to check.
expected (string)	Substring that must be present in the variable’s value.

assertArrayEquals()

Fail if an indexed array’s contents do not exactly match the expected values.

args

varName (arrayRef)	Name of the indexed array variable to check.
expected (string)	Remaining args are the expected element values in order.

assertHashTableIsDefined()

Fail if a variable is not defined as an associative array (hash table).

args

varName	(mapRef) Name of the variable that must be a defined associative array.

assertHashTableIsNotDefined()

Fail if an associative array variable is currently defined.

args

varName	(mapRef) Name of the variable that must not be defined.

assertHashKeyIsDefined()

Fail if a key is not present in an associative array.

args

varName	(mapRef) Name of the associative array variable.
keyName (string)	Key that must be defined in the array.

assertHashKeyIsNotDefined()

Fail if a key is present in an associative array.

args

varName	(mapRef) Name of the associative array variable.
keyName (string)	Key that must NOT be defined in the array.

assertHashValue()

Fail if the value at a key in an associative array does not equal the expected value.

args

varName	(mapRef) Name of the associative array variable.
keyName (string)	Key to look up.
expectedValue (string)	Expected value at that key.

Path Functions

prependPath()

Prepend a directory to a PATH-style variable, removing any existing occurrence first.

args

path (string)	Name of the directory to prepend.
pathVariable (string)	Name of the colon-separated path variable (default: PATH).

appendPath()

Append a directory to a PATH-style variable, removing any existing occurrence first.

args

path (string)	Name of directory to append.
pathVariable (string)	Name of the colon-separated path variable (default: PATH).

removePath()

Remove all occurrences of a directory from a colon-separated path variable.

args

removePath (string)	Directory path to remove.
pathVariable (string)	Name of the path variable to modify (default: PATH). [R/W]

printPath()

Print a PATH-style variable with each directory on its own numbered line.

args

pathVariable (string)	Name of the colon-separated path variable to display (default: PATH).

addRayvnProject()

Register a rayvn project by name and root directory, resolving symlinks via realpath.

args

projectName (string)	Name to register the project under.
projectRoot (string)	Path to the project root directory (resolved to real path).

returns

0	project successfully registered
1	project already registered with the same root (no-op)

removeRayvnProject()

Unregister a project previously added with addRayvnProject().

args

projectName (string)	Name of the project to remove.

requireAndAssertFailureContains()

Require a library and assert the failure message contains an expected substring.

args

library (string)	Path to require (e.g. ‘rayvn/core’).
expected (string)	Substring that must appear in the captured failure message.

benchmark()

Run a function N times and print timing results including ops/sec.

args

functionName (string)	Name of the function to benchmark.
iterations (int)	Number of times to call the function.
testCase (string)	Label printed in the results line.
[...] (string)	Optional arguments passed to the function on each invocation.

Tty Capture Functions

startTtyCapture()

Begin capturing terminal UI output to a temp file. Access captured output via getTtyOutput() or getTtyText(). Pair with stopTtyCapture() to restore.

stopTtyCapture()

Stop capturing and restore terminal UI output to the original terminal device.

clearTtyCapture()

Clear the tty capture file content without stopping capture.

getTtyOutput()

Return raw tty capture content including all ANSI escape sequences.

getTtyText()

Return tty capture content with all ANSI escape sequences stripped.

assertTtyRawContains()

Fail if raw (ANSI-encoded) tty capture content does not contain expected as a substring. Use this to assert on escape sequences directly. Use assertTtyContains for visible text.

args

expected (string)	Substring that must be present in raw tty output (e.g. $’\e[?25l’).
msg (string)	Optional failure message.

assertTtyContains()

Fail if captured tty text does not contain expected as a substring.

args

expected (string)	Substring that must be present in tty output.
msg (string)	Optional failure message.

assertTtyNotContains()

Fail if captured tty text contains expected as a substring.

args

expected (string)	Substring that must NOT be present in tty output.
msg (string)	Optional failure message.

Input Simulation Functions

startInputSimulation()

Begin simulating user input from a string. Redirects stdinFd to a temp file containing the given input so prompt functions read from it instead of the terminal. Pair with stopInputSimulation() to restore.

args

input (string)	The simulated input (e.g. “y” for a confirm, “2” for a choice).

stopInputSimulation()

Stop simulating user input and restore stdinFd to the real stdin.