Usage Guide (libtest)

Introduction

This page describes how to use the libtest library.

The library implements a great deal of functionality, almost all of which is used and only used by the libtest library itself. From the point of view of an external caller to its API, there are only a few functions; a couple to init and run the entire test suite, a few more to handle the results from a test run, and one or two miscellanous functions.

Usage

To use libtest, include the header file libtest.h and link as normal to the library in your build.

Dependencies

The libtest libraries depends on the libshared library and the liblfds711 library.

Source Files

└── test_and_benchmark
    └── libtest
        ├── inc
        │   └── libtest
        │       ├── libtest_misc.h
        │       ├── libtest_results.h
        │       └── libtest_testsuite.h
        └── src
            ├── libtest_misc
            │   └── libtest_misc_determine_erg.c
            ├── libtest_results
            │   ├── libtest_results_cleanup.c
            │   ├── libtest_results_get_result.c
            │   ├── libtest_results_init.c
            │   └── libtest_results_internal.h
            └── libtest_testsuite
                ├── libtest_testsuite_cleanup.c
                ├── libtest_testsuite_init.c
                ├── libtest_testsuite_internal.h
                └── libtest_testsuite_run.c

This is a small subset of the full set of files, and shows only those files used by the publically exposed APIs.

Enums

enum lfds711_misc_validity
enum libtest_misc_determine_erg_result
enum libtest_test_id

Opaque Structures

struct libtest_results_state
struct libtest_testsuite_state
struct libshared_memory_state

Prototypes

void libtest_testsuite_init( struct libtest_testsuite_state *ts,
                             struct libshared_memory_state *ms,
                             void (*callback_test_start)(char *test_name),
                             void (*callback_test_finish)(char *result) );
void libtest_testsuite_cleanup( struct libtest_testsuite_state *ts );
void libtest_testsuite_run( struct libtest_testsuite_state *ts,
                            struct libtest_results_state *rs );

void libtest_results_init( struct libtest_results_state *rs );
void libtest_results_cleanup( struct libtest_results_state *rs );
void libtest_results_get_result( struct libtest_results_state *rs,
                                 enum libtest_test_id test_id,
                                 enum lfds711_misc_validity *result );

void libtest_misc_determine_erg( struct libshared_memory_state *ms,
                                 lfds711_pal_uint_t (*count_array)[10],
                                 enum libtest_misc_determine_erg_result *der,
                                 lfds711_pal_uint_t *erg_length_in_bytes );

Overview

To run the tests, take the following steps;

1. Initialize a struct libshared_memory_state, with enough store (at least 4mb). The test code is not NUMA aware, so no special NUMA-aware allocations are required.
2. Initialize a struct libtest_results_state.
3. Initialize a struct libtest_testsuite, passing in the libshared_memory_state initialized earlier.
4. Call libtest_testsuite_run, passing in the struct libtest_testsuite_state and the struct libtest_results_state.

When libtest_testsuite_run returns, the struct libtest_results_state will be populated, and it can be queried with libtest_results_get_result.

A given initialized struct libtest_testsuite can be passed any number of times to libtest_testsuite_run. The struct libtest_results however must be initialized, or a new struct provided, between calls, as this structure only stores the results of a single test run.

See Also

• Usage Guide (testing)