---

4.4.3 Test Execution Report

This section documents the reported data from an execution of a provided test.

C Data Type: micro_benchmark_exec_report ¶

Opaque representation of the information collected from a test case execution. Certain constraints, such as size dimensions, require several executions of the same test case.

The lifetime of these objects is bound to the suite that generated them. Calling micro_benchmark_suite_release ends the lifetime of all reports associated to that suite.

C Report Function: const char * micro_benchmark_exec_report_get_name (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned points to a valid, zero-ended array of characters, representing the name of this test execution.

C Report Function: void micro_benchmark_exec_report_get_sizes (micro_benchmark_exec_report report, const size_t **sizes, size_t *dimensions) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. sizes must point to a valid object.
3. dimensions must point to a valid object.

Effects:

1. None.

Postconditions:

1. The object pointed by dimensions contains the size of the array pointed by sizes, or zero.
2. If dimensions is zero, the value of the object pointed by sizes is not changed. When dimensions is greater than zero, The object pointed by sizes points to an array of  objects whose values are equivalent to the ones provided for the test execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_num_time_samples (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The number of time samples stored on report.

C Report Function: micro_benchmark_time_sample micro_benchmark_exec_report_get_time_sample (micro_benchmark_exec_report report, size_t n) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.
2. n is less than the value returned by micro_benchmark_exec_report_get_num_time_samples (report).

Effects:

1. None.

Postconditions:

1. The value returned is the the time sample n collected by the test case execution associated to report.

The following functions access to the aggregated statistical data of the test execution report.

C Report Function: size_t micro_benchmark_exec_report_get_iterations (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the number of sampled iterations by the test case execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_total_iterations (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the total number of iterations performed by the test case execution associated to report.

C Report Function: micro_benchmark_clock_time micro_benchmark_exec_report_total_time (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the total time, including library overhead, spent on the test case execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_total_samples (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the total number of samples collected by the test case execution associated to report.

C Report Function: size_t micro_benchmark_exec_report_used_samples (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned is the number of samples used for the statistical data aggregation of the test case execution associated to report.

C Report Function: micro_benchmark_stats_value micro_benchmark_exec_report_iteration_time (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned contains the statistical values calculated with regard of the time elapsed per iteration of the test case execution associated to report.

C Report Function: micro_benchmark_stats_value micro_benchmark_exec_report_sample_time (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned contains the statistical values calculated with regard of the sample time of the test case execution associated to report.

C Report Function: micro_benchmark_stats_value micro_benchmark_exec_report_sample_iterations (micro_benchmark_exec_report report) ¶

Preconditions:

1. report must have been obtained as the return value of a call to micro_benchmark_test_report_get_exec_report.

Effects:

1. None.

Postconditions:

1. The value returned contains the statistical values calculated with regard of the iterations per sample of the test case execution associated to report.

The report can contain additional data collected during the test execution (see Custom Data Collection Reference.)

Note: This API is still on a very early stage, expect changes.

C Data Type: micro_benchmark_report_extra_data { const char*name, size_t size, const char **keys, const char**values } ¶

Additional data collected. name identifies the data. The length of keys and values must be greater or equal than size.

C Function Type: micro_benchmark_report_extractor_fun ¶

Extract a printable representation of the collected data. Its prototype is micro_benchmark_report_extra_data (*) (void *).

C Report Function: size_t micro_benchmark_exec_report_number_of_meters (micro_benchmark_exec_report report) ¶

Note: Not specified yet.

Return the number of custom meters whose data has been collected onto report.

C Report Function: size_t micro_benchmark_exec_report_meter_num_samples (micro_benchmark_exec_report report, size_t meter) ¶

Note: Not specified yet.

Return the number of samples collected by meter onto report. meter must be less than the value returned by micro_benchmark_exec_report_number_of_meters.

C Report Function: micro_benchmark_stats_sample_type micro_benchmark_exec_report_meter_sample_type (micro_benchmark_exec_report report, size_t meter) ¶

Note: Not specified yet.

Return the type of samples collected by meter onto report. meter must be less than the value returned by micro_benchmark_exec_report_number_of_meters.

C Report Function: micro_benchmark_stats_generic_sample micro_benchmark_exec_report_meter_get_sample (micro_benchmark_exec_report report, size_t meter, size_t pos) ¶

Note: Not specified yet.

Return the sample pos collected by meter onto report. meter must be less than the value returned by micro_benchmark_exec_report_number_of_meters (report) and pos must be less than the value returned by micro_benchmark_exec_report_meter_num_samples.

C Report Function: micro_benchmark_report_extra_data micro_benchmark_exec_report_get_extra_data (micro_benchmark_exec_report report, size_t pos) ¶

Note: Not specified yet.

Extract the custom data stored on report from meter pos.