DESCRIPTION

NAME:

API Sanity Checker (api-sanity-checker) Generate basic unit tests for a C/C++ library API

DESCRIPTION:

API Sanity Checker is an automatic generator of basic unit tests for a C/C++ library. It helps to quickly generate simple ("sanity" or "shallow" quality) tests for every function in an API using their signatures, data type definitions and relationships between functions straight from the library header files ("Header-Driven Generation"). Each test case contains a function call with reasonable (in most, but unfortunately not all, cases) input parameters. The quality of generated tests allows one to check absence of critical errors in simple use cases and can be greatly improved by involving of highly reusable specialized types for the library.

The tool can execute generated tests and detect crashes, aborts, all kinds of emitted signals, non-zero program return code, program hanging and requirement failures (if specified). The tool can be considered as a tool for out-of-box low-cost sanity checking of library API or as a test development framework for initial generation of templates for advanced tests. Also it supports universal Template2Code format of tests, splint specifications, random test generation mode and other useful features.

This tool is free software: you can redistribute it and/or modify it under the terms of the GNU LGPL or GNU GPL.

USAGE:

api-sanity-checker [options]

EXAMPLE:

api-sanity-checker -lib NAME -d VER.xml -gen -build -run

VERSION.xml is XML-descriptor:

<version>

1.0

</version>

<headers>

/path1/to/header(s)/ /path2/to/header(s)/

...

</headers>

<libs>

/path1/to/library(ies)/ /path2/to/library(ies)/

...

</libs>

INFORMATION OPTIONS:

-h|-help

Print this help.

-info

Print complete info.

-v|-version

Print version information.

-dumpversion

Print the tool version (1.98.7) and don't do anything else.

GENERAL OPTIONS:

-l|-lib|-library NAME

Library name (without version).

-d|-descriptor PATH

Path to the library descriptor (VER.xml file):

<version>

1.0

</version>

<headers>

/path1/to/header(s)/ /path2/to/header(s)/ ...

</headers>

<libs>

/path1/to/library(ies)/ /path2/to/library(ies)/ ...

</libs>

For more information, please see:

http://lvc.github.com/api-sanity-checker/Xml-Descriptor.html

-gen|-generate

Generate test(s). Options -l and -d should be specified. To generate test for the particular function use it with -f option. Exit code: number of test cases failed to build.

-build|-make

Build test(s). Options -l and -d should be specified. To build test for the particular function use it with -f option. Exit code: number of test cases failed to generate.

-run

Run test(s), create test report. Options -l and -d should be specified. To run test for the particular function use it with -f option. Exit code: number of failed test cases.

-clean

Clean test(s). Options -l and -d should be specified. To clean test for the particular function use it with -f option.

EXTRA OPTIONS:

-vnum NUM

Specify library version outside the descriptor.

-s|-symbol NAME

Generate/Build/Run test for the specified function (mangled name in C++).

-symbols-list PATH

This option allows one to specify a file with a list of functions (one per line, mangled name in C++) that should be tested, other library functions will not be tested.

-header NAME

This option allows one to restrict a list of functions that should be tested by providing a header file name in which they are declared. This option is intended for step-by-step tests development.

-all

Generate tests for all symbols recursively included in header file(s).

-xvfb

Use Xvfb-server instead of current X-server (default) for running tests.

-t2c|-template2code

Generate tests in the universal Template2Code format. For more information, please see:

http://sourceforge.net/projects/template2code/

-strict-gen

Terminate the process of generating tests and return error code '1' if cannot generate at least one test case.

-strict-build

Terminate the process of building tesst and return error code '1' if cannot build at least one test case.

-strict-run

Terminate the process of running tests and return error code '1' if at least one test case failed.

-strict

This option enables all -strict-* options.

-r|-random

Random test generation mode.

-min

Generate minimun code, call functions with minimum number of parameters to initialize parameters of other functions.

-max

Generate maximum code, call functions with maximum number of parameters to initialize parameters of other functions.

-show-retval

Show the function return type in the report.

-check-retval

Insert requirements on return values (retval!=NULL) for each called function.

-st|-specialized-types PATH

Path to the file with the collection of specialized types. For more information, please see:

http://lvc.github.com/api-sanity-checker/Specialized-Type.html

-td|-test-data PATH

Path to the directory with the test data files. For more information, please see:

http://lvc.github.com/api-sanity-checker/Specialized-Type.html

-headers-only

If the library consists of inline functions only and has no shared objects then you should specify this option.

-no-inline

Don't generate tests for inline functions.

-keep-internal

Generate tests for internal symbols (functions with '__' prefix and methods of classes declared inside other classes).

-isolated

Allow to restrict functions usage by the lists specified by the -functions-list option or by the group devision in the descriptor.

-view-only

Remove all files from the test suite except *.html files. This option allows one to create a lightweight html-index for all tests.

-disable-default-values

Disable usage of default values for function parameters.

-optimize-includes LEVEL

Enable optimization of the list of included headers in each test case. Available levels:

High (default) Medium Low None - disable

-p|-params PATH

Path to file with the function parameter names. It can be used for improving generated tests if the library header files don't contain parameter names. File format:

func1;param1;param2;param3 ... func2;param1;param2;param3 ... ...

-title NAME

The name of the library in the report title.

-relpath|-reldir PATH

Replace {RELPATH} in the library descriptor by PATH.

-lang LANG

Set library language (C or C++). You can use this option if the tool cannot auto-detect a language.

-target COMPILER

The compiler that should be used to build generated tests under Windows. Supported:

gcc - GNU compiler cl - MS compiler (default)

-debug

Write extended log for debugging.

-cache

Cache the ABI dump and use it on the next run.

OTHER OPTIONS:

-test

Run internal tests. Create a simple library and run the tool on it. This option allows one to check if the tool works correctly on the system.

-disable-variable-reuse

Disable reusing of previously created variables in the test.

-long-variable-names

Enable long (complex) variable names instead of short names.

MORE INFORMATION:

http://lvc.github.com/api-sanity-checker/

AUTHOR

This manual page was written by Mathieu Malaterre <[email protected]> for the Debian GNU/Linux system (but may be used by others).

Written by Andrey Ponomarenko.

COPYRIGHT

Copyright © 2015 Andrey Ponomarenko's ABI Laboratory License: LGPL or GPL <http://www.gnu.org/licenses/> This program is free software: you can redistribute it and/or modify it.