std.unittest

Function Description

The Unittest library is used to compile unit test code for the Cangjie project. It provides basic functions including code writing, running, and debugging, and some advanced functions for experienced users. The Cangjie unit test supports the CJC compiler (single-package compilation mode) and CJPM package manager (multi-package mode).

You can write the first unit test program following the Quick Start Guide. The document describes some basic concepts and usage and provides sample code. It also describes some advanced features, such as parameterized tests.

The following APIs are re-exported from other packages. You may import unittest alone.

APIs re-exported from the unittest.common package

Interface

Interface	Description
DataProvider	Specifies a component of DataStrategy, which is used to provide test data. T specifies the data type provided by the provider.
DataShrinker	Specifies a component of DataStrategy, which is used to reduce data during testing. T specifies the type of data processed by the shrinker.
DataStrategy	Specifies a strategy that provides data for parameterized tests. T specifies the data type that the strategy operates on.

Class

Class	Description
Configuration	Specifies an object for storing the `unittest` configuration data generated by the `@Configure` macro. `Configuration` is a class similar to `HashMap`, but its key is not of a key or value type but of a `String` type and its value is of any given type.
ConfigurationKey	Specifies a key value of a configuration item. Provides the equality comparison and hashCode methods.

APIs re-exported from the unittest.prop_test package

Function

Function	Description
random<T>()	Generates random data of type T. T must implement the Arbitrary<T> interface. The returned value of this function is a parameter source for parameterized tests.

Interface

Interface	Description
Arbitrary	Generates a random value of type T.
Shrink	Shrinks a T-type value to multiple "smaller" values.

API List

Function

Name	Description
assertCaughtUnexpectedE(String, String, String, Option<AssertionCtx>)	Records information without throwing any exception if a caught exception does not meet the expectation.
assertEqual<T>(String, String, T, T, Option<AssertionCtx>)	Checks whether the value of `expected` is equal to that of `actual`. If not, an exception is thrown.
defaultConfiguration()	Generates default configuration information.
entryMain(TestPackage)	Provides the entry function for the `cjc --test` framework to execute test cases.
expectCaughtUnexpectedE(String,String,String, Option<AssertionCtx>)	Records information without throwing any exception if a caught exception does not meet the expectation.
expectEqual(String, String, T, T, Option<AssertionCtx>)	Checks whether the value of `expected` is equal to that of `actual`. Records the comparison result and does not throw an exception.
fail(String)	Makes the case fail and throws an exception.
failExpect(String)	Makes the case fail and records the information without throwing any exception.
invokeCustomAssert<T>(Array<String>, String, (AssertionCtx) -> T, Option<AssertionCtx>)	Runs the custom assertion function specified by `@Assert[caller](passerArgs)` used in the `@Test`, `@TestCase`, or `@CustomAssertion` macro.
invokeCustomExpect<T>(Array<String>, String, (AssertionCtx) -> Any, Option<AssertionCtx>)	Runs the custom assertion function specified by `@Expect[caller](passerArgs)` used in the `@Test`, `@TestCase`, or `@CustomAssertion` macro.

Type Alias

Name	Description
MeasurementUnitTable	Specifies a measurement instance for the performance test.

Interface

Name	Description
BenchInputProvider	Specifies an interface used to handle performance testing. It requires executing specific code before each invocation of the performance test. When the input for the performance test changes, the input data must be regenerated from scratch each time.
BenchmarkConfig	Specifies an empty interface that differentiates certain Configuration functions as performance-related configurations.
BenchmarkInputMarker	Detects `BenchInputProvider<T>` when `T` is not known.
Generator	Generates a value of type T.
Measurement	Specifies an interface for collecting and analyzing various types of data during the performance test. The specific instance of `Measurement` used during the performance test is specified in the `@Measure` macro (for example, in the class declaration).
TestClass	Provides the method for creating a TestSuite.

Class

Name	Description
AssertionCtx	Stores the status of custom assertions. Provides methods for writing custom assertions.
Benchmark	Provides methods for creating and running individual performance test cases.
BenchReport	Provides capabilities for handling performance test case execution result reports.
CartesianProductProcessor	Specifies the Cartesian product processor.
ConsoleReporter	Prints the unit test case results or performance test case results to the console.
CsvReporter	Prints the performance test case results to a CSV file.
CsvRawReporter	Prints the performance test case results, which contain only a batch of raw measurement data, to a CSV file.
CsvStrategy	Indicates serialization implementation by `DataStrategy` on the CSV data format.
DataStrategyProcessor	Specifies a base class for all DataStrategy components. Instances of this class are created by the @Strategy macro or member function.
FlatMapProcessor	Specifies a processor for handling parameter data with FlatMap.
FlatMapStrategyProcessor	Specifies a processor for handling parameter data with FlatMap.
InputParameter	Specifies an input parameter object type.
JsonStrategy	Indicates serialization implementation by `DataStrategy` on the JSON data format.
LazyCyclicNode	Specifies an internal lazy iterator used to advance type erasure one after another in a loop.
MapProcessor	Processor for handling parameter data with Map.
PowerAssertDiagramBuilder	Specifies a builder of the PowerAssert output result.
RandomDataProvider	Indicates DataProvider implementation generated using random data.
RandomDataShrinker	Indicates DataShrinker implementation generated using random data.
RandomDataStrategy	Indicates DataStrategy implementation generated using random data.
RawStatsReporter	Specifies a reporter for raw performance test data. It is used only within the framework.
Report	Specifies a base class for printing test case result reports.
SerializableProvider	Indicates DataProvider implementation for obtaining serialized data.
SimpleProcessor	Specifies a simple data strategy processor. Implementation of DataStrategyProcessor.
TestGroup	Provides methods for building and running test groups.
TestGroupBuilder	Provides methods for configuring test groups.
TestPackage	Specifies the test case package object.
TestReport	Provides the unit test result report.
TestSuite	Provides methods for building and executing test suites.
TestSuiteBuilder	Provides methods for configuring test suites.
UnitTestCase	Provides methods for creating and executing unit test cases.
XmlReporter	Prints the unit test case result data to an XML file.

Enumeration

Name	Description
ExplicitGcType	Specifies `explicitGC` configuration parameters for the `@Configure` macro. Indicates three GC execution methods.
TimeUnit	Specifies a time unit that can be used in the `TimeNow` class constructor.
PerfCounter	Enumerates the CPU counters supported by the Perf constructor.

Struct

Name	Description
BatchInputProvider	Specifies an input provider that generates the input for the entire benchmark batch in the buffer before execution.
BatchSizeOneInputProvider	Specifies a benchmark input provider that generates input before each benchmark execution.
CpuCycles	Uses the local `rdtscp` instruction to measure the number of CPU cycles. It applies only to the x86 platform.
GenerateEachInputProvider	Specifies a benchmark input provider that generates input before each benchmark execution.
ImmutableInputProvider	Specifies the simplest input provider that merely copies data for each benchmark call. It is applicable to the scenario where the benchmark test does not change the input. This is the default provider used within the framework.
Perf	Uses the Linux system call `perf_event_open` to measure various hardware and software CPU counters. It is available only on Linux.
TimeNow	Indicates implementation of Measurement, used to measure the time taken to execute a function.

Exception Class

Name	Description
AssertException	Specifies an exception thrown when an @Expect / @Assert check fails.
AssertIntermediateException	Specifies an exception thrown when a @PowerAssert check fails.
UnittestCliOptionsFormatException	Specifies an exception thrown when there is a format error in the console options.
UnittestException	Specifies a general exception for the framework.