Skip to main content

Test System

Alia's test system provides four keywords — test, assert, inspect, and breakpoint — for writing and running tests.

1. Test Keywords​

test — Declaring a test block​

test <String what> <Stack content>

test declares a test block, which consists of a test name and the test content.

assert — Assertion​

assert <Boolean what>
assert <Boolean what> error <String errorMessage>

assert asserts that a condition is true and throws an error if the condition is false. The error keyword specifies the error message used when the assertion fails.

inspect — Generating equality assertions​

inspect <Value what>
inspect <Value what> error <String errorMessage>

inspect generates an equality assertion at the current position in the test code, automatically converting the expression into a comparison against its execution result. For example, after const v = 2, inspect v error 'Error' is converted into assert v == 2 'Error'. The error keyword specifies the error message used when the assertion fails.

breakpoint — Breakpoint​

breakpoint

breakpoint enters an interactive Aliaẞhell, keeping the current context intact. Code entered is executed immediately, with direct access to variables in the current scope. Press Ctrl+C to exit the shell.

2. Basic Usage​

Basic assertions​

test 'basic-assert' {
  assert 1 + 1 == 2
  assert 1 + 1 == 2 error 'Addition assertion failed'
  assert 'hello' .. ' ' .. 'world' == 'hello world' error 'String concatenation failed'
}

test 'numeric-assertions' {
  assert 10 > 5
  assert 10 > 5 error 'Numeric comparison failed'
  assert 3 * 4 == 12 error 'Multiplication assertion failed'
  assert 10 % 3 == 1 error 'Modulo assertion failed'
}

Generated assertions​

test 'inspect-basics' {
  const a = 1
  inspect a
  inspect a error 'Variable value check failed'

  const b = 2 + 2
  inspect b
  inspect b error 'Expression value check failed'
}

Null assertions​

Ok determines whether an expression is non-null. In assert, when Ok is followed by a variable, it must be wrapped in parentheses; otherwise the expression cannot be parsed.

test 'null-check' {
  let value = null
  assert !(Ok value) error 'value should be null'
  value = 42
  assert (Ok value) error 'value should not be null'
}

3. Interaction with Error Handling​

test 'error-handling' {
  let error_caught = false
  try {
    throw 'Test error'
  } catch e {
    error_caught = true
  }
  assert error_caught == true error 'Error catching failed'
}

test 'nested-error-handling' {
  let outer_error = null
  try {
    try {
      throw 'Inner error'
    } catch inner {
      outer_error = inner
      throw 'Outer error'
    }
  } catch outer {
    outer_error = outer
  }
  assert outer_error == 'Outer error' error 'Nested error handling failed'
}

4. Assertions in Conditionals and Loops​

test 'conditional-assertions' {
  const n = 5
  let result = 0
  if n > 0 {
    result = 1
  }
  assert result == 1 error 'Conditional branch assertion failed'
}

test 'loop-assertions' {
  let sum = 0
  for { let i = 0 } i < 5 { i++ } {
    sum = sum + i
  }
  assert sum == 10 error 'Loop summation failed'
}

5. Global Mode Interface​

Alia provides three dimensions of execution modes, passed in at call time via the options parameter:

Interpret/Compile dimension (interpretMode)​

ModeDescription
'interpret'Interpretation mode (default)
'compile'Compilation mode

Run/Test dimension (executeMode)​

ModeDescription
'run'Run mode (default) — skips all test blocks entirely without executing them
'test'Test mode — executes test blocks; can be combined with testFilters to filter specific test modules

Code source dimension (sourceMode)​

ModeDescription
'code'Direct code string (default)
'file'Read code from a file
'project'Read code from a project

Behavior notes​

  • In run mode, test blocks are skipped and no test code is executed
  • In test mode, test blocks are executed, running in isolated execution stacks
  • A failed assert or inspect throws an error, causing the entire test to fail
  • An empty testFilters array means all tests are executed; otherwise only the tests in the filter list run
  • After each test executes, a [TEST PASSED] or [TEST FAILED] marker is printed

6. Running Tests​

The test entry point is located at Base/Executor/Tests/test.js; targets and options control the scope of execution.

node Tests/test.js [target] [options]
TargetDescription
nativeRun the Alia interpreter tests
compile-jsRun the compile-to-JS tests
compile-nodejsRun the compile-to-Node.js tests
compile-rsRun the compile-to-Rust tests
systemRun the JS system unit tests
allRun all tests (default)
OptionDescription
--filters, -f <patterns>Filter by file name (comma-separated)
--tests, -t <patterns>Filter by test block name (comma-separated)
--run, -rRun mode; skips test blocks
--errors-only, -eOutput errors only
--help, -hShow help

npm scripts provided by Base/Executor:

npm test                    # Run all tests
npm run test:native         # Run the interpreter tests
npm run test:compile-js     # Run the JS compilation tests
npm run test:compile-nodejs # Run the Node.js compilation tests
npm run test:compile-rs     # Run the Rust compilation tests
npm run test:system         # Run the system unit tests

7. Complete Example​

~ Complete example of the Alia test system

test 'basic-assert' {
  assert 1 + 1 == 2
  assert 1 + 1 == 2 error 'Addition assertion failed'
  assert 'hello' .. ' ' .. 'world' == 'hello world' error 'String concatenation failed'
}

test 'inspect-basics' {
  const a = 1
  inspect a
  inspect a error 'Variable value check failed'
  const b = 2 + 2
  inspect b
  inspect b error 'Expression value check failed'
}

test 'error-handling' {
  let error_caught = false
  try {
    throw 'Test error'
  } catch e {
    error_caught = true
  }
  assert error_caught == true error 'Error catching failed'
}

test 'multiple-assertions' {
  const x = 10
  assert x > 0 error 'Positive number assertion failed'
  assert x < 20 error 'Range check failed'
  assert x == 10 error 'Exact value check failed'
}

Next Steps​