assert

Checks a condition when testing is enabled.

assert, assert_true and asserttrue check that a value is true. assert_false and assertfalse check that it is false. All five names use the same testing option and reporting rules.

Syntax

ModernClassic

assert(condition)
assert_true(condition)
asserttrue(condition)
assert_false(condition)
assertfalse(condition)

assert condition
assert_true condition
asserttrue condition
assert_false condition
assertfalse condition

Initialization

condition is a Boolean expression or a numeric value. Zero is false. Any nonzero number is true, including a negative number. The opcodes have no outputs and take no message argument.

Opcode names	Passes when
assert, assert_true, asserttrue	The condition is true or the number is nonzero
assert_false, assertfalse	The condition is false or the number is zero

The current implementation checks at initialization only. It accepts constants, p-fields, i-rate and k-rate numeric values, and i-rate and k-rate Boolean inputs. A k-rate input does not make the assertion run on every control cycle. Use values and expressions that are ready at initialization, since a k-rate expression may not yet have been evaluated.

Audio signals, strings and arrays are not accepted directly. To check an array, for example, compare its length or an individual numeric element.

Enabling checks

Add --run-unit-tests to the command line or <CsOptions> to enable the checks. Without this option, the assertions record no checks or failures, so you can leave them in a musical composition for normal playback. Their argument expressions still follow the usual Csound evaluation rules.

When a check fails, Csound adds an error and continues running. At the end it prints a unit test report, and the command-line program returns a nonzero exit status if errors occurred. These opcodes do not print a separate message for each failed check.

Examples

The main use is testing Csound itself in command-line tests. Assertions can also check assumptions in a composition, such as whether moving up twelve MIDI notes doubles the frequency.

This example plays two notes and checks their pitch calculations and amplitude. It uses assert.csd.

<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr 1
  iMidiNote = p4
  iFrequency = cpsmidinn(iMidiNote)
  iOctaveFrequency = cpsmidinn(iMidiNote + 12)
  iAmplitude = 0.1

  ; These checks only count when --run-unit-tests is enabled.
  assert(iFrequency > 0)
  ; Allow a small rounding difference in the pitch calculation.
  assert_true(abs(iOctaveFrequency - 2 * iFrequency) < 0.000001)
  assert_false(iAmplitude < 0 || iAmplitude > 1)

  aEnvelope linseg 0, 0.01, iAmplitude, p3 - 0.02, iAmplitude, 0.01, 0
  aTone poscil aEnvelope, iFrequency
  out aTone
endin
</CsInstruments>
<CsScore>
i 1 0 1 60
i 1 1.2 1 69
e
</CsScore>
</CsoundSynthesizer>

Play the notes with checks disabled.

csound assert.csd

Run the same piece as a test without audio output.

csound --run-unit-tests -n assert.csd

The report should show six assertions passed, three for each note. To see a failure, change the expected octave ratio from 2 * iFrequency to 3 * iFrequency. Each note will then fail one check when testing is enabled.

See also

Testing, Command-line options

Credits

Opcodes by Hlöðver Sigurðsson, 2025.

New in Csound 7.