api-sanity-checker

API(1)                           User Commands                          API(1)



   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 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 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 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 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 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.

   EXIT CODES:
              0 - Successful tests. The tool has run without any errors.
              non-zero - Tests failed or the tool has run with errors.

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

AUTHOR
       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.



API Sanity Checker 1.98.7        January 2019                           API(1)