Documentation

Write Single Tests

 Note:   Use only in the MuPAD Notebook Interface. This functionality does not run in MATLAB.

The `prog::test` function is the basic testing tool in MuPAD®. This function compares the actual result of computations with the expected result that you specify. For example, create the procedure `f`:

```f := proc(a:Type::Numeric, b:Type::Numeric) begin if a = b or a > b then return(a) else return(b) end_if end_proc:```

To test the procedure, use the `prog::test` function. If the test does not reveal any problems, `prog::test` returns the void object `null()` and does not print anything:

`prog::test(f(I, I), I)`

If the procedure call tested by `prog::test` errors or if actual results differ from expected results, `prog::test` prints information about the test execution. For example, if your test compares two different complex numbers, `prog::test` returns the following message:

`prog::test(f(2*I, I), I)`
`Error in test 2`
`Input: f(2*I, I)`
`Expected: I`
`Got: TrapError = [1003, message("symbolic:kernel:NotBoolean")]`
`Near line: 1`

If the error is expected, you can rewrite the test using the `TrapError` option:

`prog::test(f(2*I, I), TrapError = 1003)`

When you call `prog::test`, MuPAD evaluates actual and expected results before comparing them:

`prog::test(f(x^2 | x = 2, 5), 2*2)`
`Error in test 4`
`Input: f(x^2 | x = 2, 5)`
`Expected: 4`
`Got: 5`
`Near line: 1`

Evaluation of actual and expected results can take a long time. To avoid long evaluations, the `prog::test` function lets you specify the time limit for evaluation of the test. To limit the evaluation time for a particular test, use the `Timeout` option of the `prog::test` function. For example, set the time limit to 2 seconds:

```prog::test(f([i! \$ i = 1..1000000], [i! \$ i = 1..1000000]), [i! \$ i = 1..1000000], Timeout = 2)```
```Error in test interactive 5```
```Input: f([i! \$ i = 1..100000], [i! \$ i = 1..100001])```
```Expected: FAIL```
```Got: TrapError = [1320, "Error: Execution time exceeded"]```
```Timeout: 2.0 (5.106*prog::ntime())```

In this example, the time limit measurement depends on your hardware configuration. The test report also shows the hardware-independent time in terms of the `prog::ntime` function.

By default, `prog::test` tests the strict equality between actual and expected results. Testing equality of floating-point values can be confusing when the display precision differs from the internal precision. In this case, different floating-point numbers can look identical. Thus, with the default values of `DIGITS` and `Pref::outputDigits`, the floating-point approximation of 1/3 and the number 0.3333333333 look identical:

`prog::test(float(1/3), 0.3333333333)`
`Error in test 5`
`Input: float(1/3)`
`Expected: 0.3333333333`
`Got: 0.3333333333`
`Near line: 1`

Internally, MuPAD uses more than 10 digits to approximate 1/3 with the floating-point number. The system adds guard digits for increased precision. To see how many guard digits the system uses, increase the number of output digits using the `Pref::outputDigits` function. Then, test the equality of the numbers again:

```Pref::outputDigits(20): prog::test(float(1/3), 0.3333333333)```
`Error in test 6`
`Input: float(1/3)`
`Expected: 0.3333333333`
`Got: 0.33333333333333333304`
`Near line: 2`

When you test equality of floating-point numbers, it can be helpful to test the approximate equality. The approximate equality operator in MuPAD is `~=`. The corresponding function is `_approx`. The `prog::test` function lets you choose the method for comparing actual and expected results. For example, 1/3 is approximately equal to 0.3333333333 within the default 10-digits precision:

`prog::test(float(1/3), 0.3333333333, Method= `~=`)`

Also, using the `Method` option lets you specify more than one acceptable solution. For example, if you randomly pick one solution of the following equation, you can get any of its four valid solutions:

```i := random(1..4): prog::test(solve(x^4 - 16 = 0, x)[i()], {-2, 2, -2*I, 2*I}, Method= _in)```

For further computations, restore the default output precision:

`Pref::outputDigits(UseDigits):`