TITLE:: UnitTest
summary:: a class for programmatic testing of classes
categories:: Testing
related:: Classes/UnitTestResult, Classes/UnitTestScript

DESCRIPTION::
In order to make sure a method works correctly, a test can be implemented that assures the correct behavior.

It is a common practice to write tests to clarify how an object should respond, and it may avoid inconsistencies on the long run. A test is always a subclass of code::UnitTest::, implementing at least one method starting with code::test_::.

When running all tests of one class (see link::#run::), each test method is called in a separate instance of this class. Test methods, therefore, do not interfere with each other.

note::
UnitTests for the Common library classes are kept in the code::testsuite/classlibrary:: directory of the SuperCollider sources.

To install, link::https://github.com/supercollider/supercollider##download the sources:: and add the directory to your code::sclang_conf.yaml::, either by editing it or via the ScIDE preferences.
::


CLASSMETHODS::

PRIVATE:: allTestClasses, classesWithTests, classesWithoutTests, failures, findTestClass, findTestClasses, findTestMethods, findTestedClass, forkIfNeeded, listUntestedMethods, passes, report, reset, run, untestedMethods

METHOD:: gui
A graphical interface to run and browse all tests

code::
UnitTest.gui
::

METHOD:: reportPasses
Accessor controlling whether passing tests should be reported.
Defaults to code::true::.  See also link::#*passVerbosity:: which
controls how much detail is reported from passing tests
when this is set to true.

ARGUMENT:: value
Should be code::true:: or code::false::.

METHOD:: passVerbosity
Accessor controlling whether extra details should be reported for
passing tests.

Defaults to code::UnitTest.full:: so that all details are reported;
however this behaviour may be too verbose for some, for whom it is
sufficient to see that a test is passing without needing to see the
detail.  If set to code::UnitTest.brief::, and link::#*reportPasses::
is true, passes will be reported, but without any extra details which
may be provided by assertions.

ARGUMENT:: value
Should be code::UnitTest.full:: or code::UnitTest.brief::.

METHOD:: run
Run all methods whose names begin with code::test_::.

code::
TestUnitTest.new.run;
::

ARGUMENT:: reset
If code::true::, first runs link::#*reset:: on the class.

ARGUMENT:: report
If code::true::, outputs the test results.

METHOD:: runTest
Run a single test method.

code::
UnitTest.reset;
UnitTest.runTest("TestUnitTest:test_assert");
::

ARGUMENT:: methodName
A link::Classes/String:: referring to the class and test method
within it, e.g. code::"TestPolyPlayerPool:test_prepareChildrenToBundle"::.


METHOD:: runAll
Run the entire test suite. As this method addresses the entire test suite, it should be called only on code::UnitTest::. Calling it on any of its subclasses will result in throwing an code::Error::.

code::
UnitTest.reset;
UnitTest.runAll;
::


INSTANCEMETHODS::

METHOD:: runTestMethod
Run a single test method of this class

code::
TestUnitTest.new.runTestMethod(TestUnitTest.findMethod(\test_assert));
::

ARGUMENT:: method
the method to run

ARGUMENT:: report
Reports the result of the test if code::true:: (default is code::true::)

returns:: (describe returnvalue here)

PRIVATE:: s, run, findTestMethods, setUp, tearDown


METHOD:: assert

Asserts that an expression must be true.

code::
this.assert(2 == 2, "passes");
this.assert(2 == 2.00001, "fails");
::

argument:: boolean
A boolean, where code::true:: means that the test is passed.

argument:: message
A message describing the purpose of the assertion, e.g. code::"foo
should be less than bar"::.
Posted if code::report:: is true.

argument:: report
Reports the result of the test if code::true::.

argument:: onFailure
If not code::nil::, a failure stops the tests and evaluates this function.

argument:: details
Some optional extra details which will be passed to the reporting framework
for display unless brief reporting is requested (see link::#*passVerbosity::).

METHOD:: assertEquals

Asserts that an expression code::a:: is equal to the value code::b::,
where equality is determined according to code::a::'s implementation
of code::==::.

Automatically passes details of the equality check to the reporting
framework, which will be displayed if the assertion fails, and also if
it passes and link::#*reportPasses:: is code::true:: and
link::#*passVerbosity:: is not set to code::UnitTest.brief::.

code::
this.assertEquals(2 + 2, 4, "passes");
this.assertEquals(2 + 2, 5, "fails");
::

argument:: a
the experimentally produced value

argument:: b
the expected value

argument:: message
A message describing the purpose of the assertion, e.g.
code::"Adding two numbers should return their sum."::.
Posted if code::report:: is true.

argument:: report
Reports the result of the test if code::true:: (default is code::true::)

argument:: onFailure
If not code::nil::, a failure stops the tests and evaluates this function.

METHOD:: assertFloatEquals

Asserts that an expression code::a:: returning a float is within a
given range (code::within::) of being equal to code::b::.

Automatically passes details of the equality check to the reporting
framework, which will be displayed if the assertion fails, and also if
it passes and link::#*reportPasses:: is code::true:: and
link::#*passVerbosity:: is not set to code::UnitTest.brief::.

code::
this.assertFloatEquals(2, 2.0001, "Pass since 2 is close enough to 2.0001.", 0.001);
this.assertFloatEquals(2, 2.0001, "Fail since 2 isn't close enough to 2.0001.", 0.0001);
::

argument:: a
the experimentally produced float value

argument:: b
the expected float value

argument:: message
A message describing the purpose of the assertion, e.g.
code::"Adding two numbers should return their sum."::.
Posted if code::report:: is true.

argument:: within
The range within which code::a:: must be of code::b:: in
order for the test to pass.

argument:: report
Reports the result of the test if code::true:: (default is code::true::)

argument:: onFailure
If not code::nil::, a failure stops the tests and evaluates this function.


METHOD:: assertArrayFloatEquals
Make sure that the two arrays of floats code::a:: and code::b:: equal within a given range (code::within::).

code::
this.assertArrayFloatEquals([2, 3] + 0.0001, [2, 3], "Pass since pairs of floats are close enough", 0.001);
this.assertArrayFloatEquals([2, 3.0001], [2, 3], "Fail since pairs of floats aren't both close enough", 0.0001);
::

argument:: a
the experimentally produced value, which is an code::Array:: of floats

argument:: b
the code::Array:: of float values expected

argument:: message
A message describing the purpose of the assertion, e.g.
code::"Arrays foo and bar should be equal."::.
Posted if code::report:: is true.

argument:: within
The range within which each item of code::a:: must be of the
corresponding item in code::b:: in order for the test to pass.

argument:: report
Reports the result of the test if code::true:: (default is code::true::)

argument:: onFailure
If not code::nil::, a failure stops the tests and evaluates this function.


METHOD:: ifAsserts
Make a further assertion only if it passed, or only if it failed.

code::
(
a = UnitTest.new;
a.ifAsserts(2 == 3, "yes", { a.assert(2 == 4) }, { a.assert(1 == 1, "but this is correct") });
)
::

method::assertException
Make sure that a specific link::Classes/Exception:: or link::Classes/Error:: is thrown.

argument:: func
Pass the code that is expected to throw an error in this function.

argument:: errorClass
The class or class name which the error should be kind of.

argument:: message
A message describing the purpose of the assertion.

argument:: report
Reports the result of the test if code::true:: (default is code::true::)

argument:: onFailure
If not code::nil::, a failure stops the tests and evaluates this function.

argument:: details
Some optional extra details which will be passed to the reporting framework
for display unless brief reporting is requested (see link::#*passVerbosity::).

method::assertNoException
Make sure that a specific link::Classes/Exception:: or link::Classes/Error:: is strong::not:: thrown.
For arguments, see link::#-assertException::.


method::wait
Wait for a predicate function to return code::true::. Considers the test failed after code::maxTime::. Only valid within a test (or a routine).

note:: It's best to avoid using this method in tests. See link::Classes/CondVar#-waitFor:: for a better option.::

code::
(
{
	s.reboot;
	UnitTest.new.wait({ s.serverRunning }, "server failed to boot in time", 2);
}.fork
)
::

METHOD:: bootServer
Wait for server boot until continued. Only valid within a test (or a routine).

If already booted, then freeAll and create new allocators.

code::
(
{
	UnitTest.new.bootServer(s);
}.fork
)
::

METHOD:: debug
Supply some debugging information relevant to the currently running
test case.  This will be displayed immediately preceding any details
which may be displayed through use of the code::details:: argument of
link::#-passed:: and link::#-failed::.

ARGUMENT:: text
The debugging text.

DISCUSSION::
code::
test_myMethod {
    var obj = MyClass.new;
    this.debug("obj has color" + obj.color);
    this.assert(2 + 2, 5);
}
::

will result in:

code::
FAIL: a TestMyClass: test_myMethod
obj has color red
Is:
         4
Should be:
         5
::

METHOD:: passed
Register a passed test.

ARGUMENT:: method
Name of the method in which the test is passing.

ARGUMENT:: message
A message describing the purpose of the assertion, e.g. code::"foo
should be less than bar"::.
Posted if neither code::report:: nor link::#*reportPasses:: are false.

argument:: report
Reports the result of the test if true and link::#*reportPasses:: is true.

argument:: details
Some optional extra details which will be displayed if
link::#*reportPasses:: is true and link::#*passVerbosity:: is
not set to code::UnitTest.brief::.

DISCUSSION::
code::
this.passed(message: "this passed");
::

METHOD:: failed
Register a test failure.

ARGUMENT:: method
Name of the method in which the test is failing.

ARGUMENT:: message
A message describing the purpose of the assertion, e.g. code::"foo
should be less than bar"::.
Posted if code::report:: is true.

argument:: report
Reports the result of the test if true.

argument:: details
Some optional extra details which will be displayed if code::report::
is true.

DISCUSSION::
code::
this.failed(message: "this failed");
::

EXAMPLES::

Write tests by subclassing UnitTest, and defining methods whose names
begins code::test_::.  Each test method will be called from a fresh
instance of the subclass.

If you implement the methods code::setUp:: and code::tearDown:: in
your test class, they will be called before and after every test.
This can help to eliminate repetitive code, and makes it easier to
maintain your tests by ensuring that they all run under the same set
of conditions.

code::
TestYourClass : UnitTest {
	setUp {
		// this will be called before each test
	}
	tearDown {
		// this will be called after each test
	}

	test_yourMethod {
		// every method whose name begins with "test_" will be run

		this.assert( 6 == 6, "6 should equal 6");

		this.assertEquals( 9, 9, "9 should equal 9");

		this.assertFloatEquals( 4.0 , 1.0 * 4.0 / 4.0  4.0,
			"floating point math should be close to equal");

		// we are inside a Routine, you may wait
		1.0.wait;

		// this will wait until the server is booted
		this.bootServer;

		// if the server is already booted it will free all nodes
		// and create new allocators, giving you a clean slate
		p = { SinOsc.ar };
		p.play;
		p.register;
		// will wait until the condition is true
		// will be considered a failure after 10 seconds
		this.wait( { p.isPlaying }, "waiting for synth to play", 10);
	}
}
::