Project Configuration

The project configuration is specified in either the autofonce.toml file. or the .autofonce file (chosen in this order).

There are actually three parts in such a project configuration file:

  • General variables, such as anchors to detect source and build directories

  • Testsuites, describing the testsuites that are available in the project

  • Environments, i.e. scripts parts to build the environment in which tests are executed

General Variables

The general variables are:

  • project.name: the name of the project. This name is not currently used, but known projects come with this name, and the name is used to autodetect that the project should use this configuration.

  • project.source_anchors: a list of files. autofonce uses this list to try to detect the source directory of the project (i.e. the project root or topdir), from where it is run. The source directory is the first directory found that contains an existing file at the specified path while moving to upper directories. If no directory is found for the first anchor, the second anchor is used, and so on. Finally, either a "!" anchor is used and triggers a failure, or the current directory is used. autofonce creates a variable AUTOFONCE_SOURCE_DIR before the test environment with the value found for this directory.

  • project.build_anchors: a list of files. autofonce must always be run from within the build directory or a sub-directory. It uses this variable similarly to source_anchors. autofonce creates a variable AUTOFONCE_BUILD_DIR before the test environment with the value found for this directory.

  • project.build_dir_candidates: a list of anchors from where to look for build_anchors. By default, autofonce uses the current directory and search for build anchors in upper directories. This option can be used to run autofonce from outside the build directory, by trying to detect the location of the build directory. Once one of the build_dir_candidates has been found, the directory it points to will be used as the current directory to find the build_anchors.

  • project.run_from: where the _autofonce/ directory will be created. This option can take 3 values: "build" for the build directory, "source" for the source directory, and "config" for the directory containing the configuration file.

  • project.captured_files: a list of paths in the source directory. If one of the tests fails, autofonce will try to include all these files into the generated _autofonce/results.log file. These files should be text files, as aufofonce does not use any encoding mechanism.

For example, for gnucobol, this section looks like:

[project]
name = "gnucobol"
source_anchors = [ "tests/testsuite.at", "!" ]
build_anchors = [ "cobc/cobc", "!" ]
build_dir_candidates = [ "_build" ]
run_from = "build"
captured_files = [ "_build/atlocal", "_build/atconfig" ]

Testsuite Descriptions

A testsuite is described by 4 components:

  • its name, used to refer to the testsuite with the -t <TESTSUITE> option (by default, autofonce uses the first testsuite described in this file).

  • its file name, i.e. the file that contains the macros for the tests. The default file name is tests/testsuite.at.

  • its path, i.e. the path in which m4_include(file) will search for file. The default path is [ "tests/testsuite.src" ]. Note that the directory containing the testsuite file name will always be added to the path.

  • its environment, i.e. the name of the environment (see next section) to use for the tests of this testsuite. The default environment is testsuite.

Such a section looks like:

[testsuites.testsuite]
file = "tests/testsuite.at"
path = [ "tests/testsuite.src"]
env = "testsuite"

If your project contains several testsuites, you can define a section for each of them, with different names, file names or environments for example.

Note that, if a testsuite is not available in the project configuration file, it is possible to specify one directly from the command line by providing the following arguments:

  • -T path/to/tests (mandatory): path to the file or directory containing the testsuite

  • -E path/to/env.sh (optional): path to a script that can be used to specify the environment (ran from every test dir)

  • -I subdir (optional): path to a subdirectory where included tests should be search in

Environment Descriptions

The environment of a test is a part of shell script, that is added at the end of the file env_autofonce.sh in each test directory.

Before, autofonce defines a few environment variables:

  • AUTOFONCE_TESTSUITE, the name of the testsuite

  • AUTOFONCE_RUN_DIR, the directory from which tests are run (containing the _autotest/ sub-directory)

  • AUTOFONCE_SOURCE_DIR, the root directory of the project

  • AUTOFONCE_BUILD_DIR, the build directory of the project

The goal of the environment part is to use these variables to translate them in variables that are used by tests to locate their dependencies.

There are two ways to define environments, for example here, we define the environment called testsuite:

  • inline environment: the environment is specified directly in this file:

    [envs]
testsuite = """
export PATH=${AUTOFONCE_BUILD_DIR}/bin:$PATH
"""

  • outside files: the environment is defined in a project file, that is referenced from here:

    [envs]
testsuite = "<tests/testsuite.env"

Note that environments can typically called the atconfig and atlocal scripts created by GNU Autoconf tools.