buildtest.cli.build

This module contains all the methods related to “buildtest build” which is used for building test scripts from a Buildspec

Module Contents

Classes

BuildTest

This class is an interface to building tests via “buildtest build” command.

Functions

discover_buildspecs(buildspecs=None, exclude_buildspecs=None, executors=None, tags=None)

This method discovers all buildspecs based on –buildspecs, –tags, –executor

discover_buildspecs_by_executor(executors)

This method discovers buildspecs by executor name, using buildtest build --executor

discover_buildspecs_by_tags(tagnames)

This method discovers buildspecs by tags, using --tags option

discover_by_buildspecs(buildspec)

Given a buildspec file specified by the user with buildtest build --buildspec,

print_discovered_buildspecs(buildspec_dict)

This method will print the discovered buildspecs in the table format

update_report(valid_builders, report_file=BUILD_REPORT)

This method will update BUILD_REPORT after every test run performed

Attributes

logger

class buildtest.cli.build.BuildTest(configuration=None, buildspecs=None, exclude_buildspecs=None, tags=None, executors=None, testdir=None, stage=None, filter_buildspecs=None, rebuild=None, buildtest_system=None, report_file=None, max_pend_time=None, poll_interval=None, keep_stage_dir=None)

This class is an interface to building tests via “buildtest build” command.

_print_build_phase(self, invalid_builders, table)
_print_jobs_after_poll(self, valid_builders)

Print table of all tests after polling

_print_test_summary(self)

Print a summary of total pass and fail test with percentage breakdown.

_update_build_history(self)

Write a build history file that is stored in $BUILDTEST_ROOT/var/.history directory summarizing output of build. The history file is a json file named build.json which contains a copy of the build log for troubleshooting. buildtest will create a sub-directory that is incremented such as 0, 1, 2 in $BUILDTEST_ROOT/var/.history which is used to differentiate builds.

_validate_filters(self)
build(self)

This method is responsible for discovering buildspecs based on input argument. Then we parse the buildspecs and retrieve builder objects for each test. Each builder object will invoke build which will build the test script, and then we run the test and update report.

build_phase(self)

This method will build all tests by invoking class method build for each builder that generates testscript in the test directory.

parse_buildspecs(self)

Parse all buildspecs by passing buildspec file to BuildspecParser class. If buildspec fails validation we skip the buildspec and print all skipped buildspecs. If buildspec passes validation we get all builders by invoking Builder class that is responsible for creating builder objects for each test.

Returns

A list of builder objects which are instances of BuilderBase class

Return type

list

poll_jobs(self, poll_queue, valid_builders)

This method will poll jobs by processing all jobs in poll_queue. If job is cancelled by scheduler, we remove this from valid_builders list. This method will return a list of valid_builders after polling. If there are no valid_builders after polling, the method will return None

Parameters
  • poll_queue (list, required) – a list of jobs that need to be polled. The jobs will poll using poll method from executor

  • valid_builders (list, required) – list of valid builders

resolve_testdirectory(self, cli_testdir=None)

This method resolves which test directory to select. For example, one can specify test directory via command line buildtest build --testdir <path> or path in configuration file. The default is $HOME/.buildtest/var/tests

Parameters

cli_testdir (str) – test directory from command line buildtest build --testdir

Returns

Path to test directory to use

Return type

str

run_phase(self)

This method will run all builders with the appropriate executor. The executor argument is an instance of BuildExecutor that is responsible for orchestrating builder execution to the appropriate executor class. The executor contains a list of executors picked up from buildtest configuration. For tests running locally, we get the test metadata and count PASS/FAIL test state which is printed at end in Test Summary. For tests that need to run via scheduler, the first stage of run will dispatch job, and state will be N/A. We first dispatch all jobs and later poll jobs until they are complete. The poll section is skipped if all tests are run locally. In poll section we regenerate table with all valid_builders and updated test state and returncode and recalculate total pass/fail tests. Finally we return a list of valid_builders which are tests that ran through one of the executors. Any test that failed to run or be dispatched will be skipped during run stage and not added in valid_builders. The valid_builders contains the test meta-data that is used for updating test report in next stage.

Returns

A list of valid builders

Return type

list

buildtest.cli.build.discover_buildspecs(buildspecs=None, exclude_buildspecs=None, executors=None, tags=None)

This method discovers all buildspecs based on –buildspecs, –tags, –executor and excluding buildspecs (–exclude).

Parameters
  • buildspecs (list) – List of input buildspecs passed by argument buildtest build –buildspec

  • exclude_buildspecs (list) – List of excluded buildspecs by argument buildtest build –exclude

  • tags (list) – List of input tags for discovering buildspecs by argument buildtest build –tags

  • executors (list) – List of input executors for discovering buildspecs by argument buildtest build –executor

buildtest.cli.build.discover_buildspecs_by_executor(executors)

This method discovers buildspecs by executor name, using buildtest build --executor command. This method will read BUILDSPEC_CACHE_FILE and search for executor key in buildspec recipe and match with input executor name. The return is a list of matching buildspec with executor name to process.

Parameters

executors (list) – List of input executor name from command line argument buildtest build --executor <name>

Returns

a list of buildspec files that match tag name

Return type

list

buildtest.cli.build.discover_buildspecs_by_tags(tagnames)

This method discovers buildspecs by tags, using --tags option from buildtest build command. This method will read BUILDSPEC_CACHE_FILE and search for tags key in buildspec recipe and match with input tag. Since tags field is a list, we check if input tag is in list and if so we add the entire buildspec into a list. The return is a list of buildspec files to process.

Parameters

input_tag (list) – List of input tags from command line argument buildtest build --tags <tags>

Returns

a list of buildspec files that match tag name

Return type

list

buildtest.cli.build.discover_by_buildspecs(buildspec)

Given a buildspec file specified by the user with buildtest build --buildspec, discover one or more files and return a list for buildtest to process. This method is called once per argument of --buildspec or --exclude option. If its a directory path we recursively find all buildspecs with option. If its a directory path we recursively find all buildspecs with .yml extension. If filepath doesn’t exist or file extension is not .yml we return None and capture error in log.

# file path buildtest build –buildspec tutorials/hello.sh.yml

# directory path buildtest build –buildspec tutorials

Parameters

buildspec (str) – Input argument from buildtest build --buildspec

Returns

A list of discovered buildspec with resolved path, if its invalid we return None

Return type

list or None

buildtest.cli.build.logger
buildtest.cli.build.print_discovered_buildspecs(buildspec_dict)

This method will print the discovered buildspecs in the table format

buildtest.cli.build.update_report(valid_builders, report_file=BUILD_REPORT)

This method will update BUILD_REPORT after every test run performed by buildtest build. If BUILD_REPORT is not created, we will create file and update json file by extracting contents from builder.metadata

Parameters
  • valid_builders (instance of BuilderBase (subclass)) – builder object that were successful during build and able to execute test

  • report_file (str) – specify location to report file