buildtest.cli.buildspec

Module Contents

Classes

BuildspecCache

The initializer method for BuildspecCache class is responsible for loading and finding buildspecs into buildspec cache. First we

Functions

edit_buildspec_test(test_names, configuration, editor)

Open a list of test names in editor mode defined by EDITOR environment otherwise resort to vim.

edit_buildspec_file(buildspecs, configuration, editor)

Open buildspec in editor and validate buildspec with parser. This method is invoked by command buildtest buildspec edit-file.

is_test_name_in_cache(test_name, cache)

Check if a test name is in the cache.

show_buildspecs(test_names, configuration[, theme])

This is the entry point for buildtest buildspec show command which will print content of

show_tests_by_status(configuration, status[, ...])

This method which will print content of

show_failed_buildspecs(configuration[, test_names, ...])

This is the entry point for buildtest buildspec show-fail command which will print content of

handle_exception(buildspec, exception)

Handle exceptions during buildspec validation.

buildspec_validate_command(configuration[, ...])

Entry point for buildtest buildspec validate. This method is responsible for discovering buildspec

summarize_buildspec_cache(pager, configuration[, color])

This is a helper method used for printing output of buildtest buildspec summary with and without

summary_print(configuration[, color])

This method will print summary of buildspec cache file. This method is the core logic

buildspec_maintainers(configuration[, breakdown, ...])

Entry point for buildtest buildspec maintainers command.

buildspec_find(args, configuration)

Entry point for buildtest buildspec find command

open_buildspec_in_editor(buildspec, editor)

Open a buildspec in the specified editor and print a message.

validate_buildspec(buildspec, configuration)

Validate a buildspec with JSON Schema and print whether it is valid or not.

Attributes

logger

buildtest.cli.buildspec.logger
class buildtest.cli.buildspec.BuildspecCache(configuration, rebuild=False, filterfields=None, formatfields=None, header=None, terse=None, pager=None, color=None, count=None, row_count=None, search_buildspecs=None)[source]

The initializer method for BuildspecCache class is responsible for loading and finding buildspecs into buildspec cache. First we resolve paths to directory where buildspecs will be searched. This can be specified via --directory option on command line or one can specify directory paths in the configuration file. Next we build the cache that contains metadata for each buildspec that will be written to file. If any filter or format options are specified we check if they are valid and finally display a content of the cache depending on the argument.

This method is called when using buildtest buildspec find command.

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – Instance of SiteConfiguration class that is loaded buildtest configuration.

  • rebuild (bool, optional) – rebuild the buildspec cache by validating all buildspecs when using buildtest buildspec find --rebuild. Defaults to False if --rebuild is not specified

  • filterfields (str, optional) – The filter options specified via buildtest buildspec find --filter that contains list of key value pairs for filtering buildspecs

  • formatfields (str, optional) – The format options used for formating table. The format option is a comma separated list of format fields specified via buildtest buildspec find --format

  • headers (bool, optional) – Option to control whether header are printed in terse output. This argument contains value of buildtest buildspec find --no-header

  • terse (bool, optional) – Enable terse mode when printing output. In this mode we don’t print output in table format instead output is printed in parseable format. This option can be specified via buildtest buildspec find --terse

  • color (str, optional) – An instance of a string class that selects the color to use when printing table output

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • row_count (bool, optional) – Print total number of records from the table

  • search_buildspecs (list, optional) – List of buildspecs to search and add into cache. This can be file or directory and this argument contains value of buildtest buildspec find --search

table
filter_fields = ['type', 'executor', 'tags', 'buildspec']
default_format_fields = ['name', 'type', 'executor', 'tags', 'description']
format_fields
get_cache()[source]

Returns cache file as loaded dictionary

load_paths()[source]

Add all paths to search for buildspecs. We read configuration file and check whether we need to load buildspecs from list of directories. We check if directories exist, if any fail we don’t add them to path. If no root directories are specified we load buildspecs in tutorials and general_tests directory.

build()[source]

This method will build buildspec cache file. If user requests to rebuild cache we remove the file and recreate cache. If cache file exists, we simply load from cache

_discover_buildspecs()[source]

This method retrieves buildspecs based on self.paths which is a list of directory paths to search. If --directory is specified we process each argument and recursively find all .yml files

_write_buildspec_cache()[source]

This method is responsible for writing buildspec cache to file

_validate_buildspecs(buildspecs)[source]

Given a list of buildspec files, validate each buildspec using buildtest.buildsystem.parser.BuildspecParser class and return a list of valid buildspecs. Any invalid buildspecs are added to separate list

Parameters:

buildspecs – A list of buildspec to validate

get_names()[source]

Return a list of test names found in buildspec cache. We only return test names for valid buildspecs

get_random_tests(num_items=1)[source]

Returns a list of random test names from the list of available test. The test are picked using random.sample

Parameters:

num_items (int, optional) – Number of test items to retrieve

lookup_buildspec_by_name(name)[source]

Given an input test name, return corresponding buildspec file found in the cache.

Parameters:

name (str) – Name of test to query in cache

Returns:

Return path to buildspec that contains name of test

build_cache()[source]

This method will rebuild the buildspec cache file by recursively searching all .yml files specified by input argument paths which is a list of directory paths. The buildspecs are validated and cache file is updated

_check_filter_fields()[source]

This method checks filter fields are valid. The filter fields are specified as buildtest buildspec find --filter <KEY1>=<VAL1>,<KEY2>=<VAL2>,...

Raises:

BuildTestError – If there is an invalid filter field

_check_format_fields()[source]

This method will check if all format fields are valid. Format fields are passed as comma separated fields: --format field1,field2,field3,...

Raises:

BuildTestError – If there is an invalid format field

_filter_buildspecs(executor, tags, schema_type)[source]

This method will return a boolean True/False that determines if buildspec test entry is skipped as part of filter process. The filter are done based on executor, tags, type field. True indicates test needs to be skipped.

Parameters:
  • executor (str) – executor property in buildspec

  • tags (list) – List of tagnames specified via `tags` property in buildspec

  • schema_type (str) – type property in buildspec

Returns:

Return True if there is no match otherwise returns False

Return type:

bool

find_buildspecs()[source]

This method will find buildspecs based on cache content. We skip any tests based on executor filter, tag filter or type filter and build a table of tests that will be printed using print_buildspecs method.

Raises:

BuildTestError – Raises exception if input buildspec for buildtest buildspec find --filter buildspec is invalid path or directory or buildspec not found in cache.

get_valid_buildspecs()[source]

Return a list of valid buildspecs

get_invalid_buildspecs()[source]

Return a list of invalid buildspecs

get_unique_tags()[source]

Return a list of unique tags.

get_unique_executors()[source]

Return a list of unique executors.

get_maintainers()[source]

Return a list of maintainers.

get_paths()[source]

Return a list of search paths

tag_breakdown()[source]

This method will return a breakdown of tags by test names.

executor_breakdown()[source]

This method will return a dictionary with breakdown of executors by test names.

test_breakdown_by_buildspec()[source]

This method will return a dictionary with breakdown of buildspecs by test names.

print_buildspecfiles(terse=None, header=None, row_count=None, count=None)[source]

This method implements buildtest buildspec find --buildspec which reports all buildspec files in cache.

Parameters:
  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

print_tags(row_count=None, count=None, terse=None, header=None)[source]

This method implements buildtest buildspec find --tags which reports a list of unique tags from all buildspecs in cache file.

Parameters:
  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

print_executors(row_count=None, count=None, terse=None, header=None)[source]

This method implements buildtest buildspec find --executors which reports all executors from cache.

Parameters:
  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

print_by_executors(row_count=None, count=None, terse=None, header=None)[source]

This method prints executors by tests and implements buildtest buildspec find --group-by-executor command

Parameters:
  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

print_by_tags(count=None, row_count=None, terse=None, header=None)[source]

This method prints tags by tests and implements buildtest buildspec find --group-by-tags command :param count: Number of entries to display in output. This argument contains value of buildtest buildspec find --count :type count: int, optional :param row_count: Print total number of records from the table :type row_count: bool, optional :param terse: This argument will print output in terse format if --terse option is specified otherwise will print output in table format :type terse: bool, optional :param header: This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option :type header: bool, optional

print_buildspecs(terse=None, header=None, quiet=None, row_count=None, count=None)[source]

Print buildspec table. This method is typically called when running buildtest buildspec find or options with --filter and --format.

Parameters:
  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

  • quiet (bool, optional) – If this option is set we return immediately and don’t anything. This is specified via buildtest buildspec find --quiet which can be useful when rebuilding cache without displaying output

  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

list_maintainers()[source]

Return a list of maintainers

print_maintainer(row_count=None, terse=None, pager=None, count=None)[source]

This method prints maintainers from buildspec cache file which implements buildtest buildspec maintainers command.

print_maintainers_find(name)[source]

Display a list of buildspec files associated to a given maintainer. This command is used when running buildtest buildspec maintainers find

Parameters:

name (str) – Name of maintainer specified via buildtest buildspec maintainers find <name>

print_maintainers_by_buildspecs()[source]

This method prints maintainers breakdown by buildspecs. This method implements buildtest buildspec maintainers --breakdown.

print_invalid_buildspecs(error=None, terse=None, row_count=None)[source]

Print invalid buildspecs from cache file. This method implements command buildtest buildspec find invalid

Parameters:
  • error (bool, optional) – Display error messages for invalid buildspecs. Default is False where we only print list of invalid buildspecs

  • terse (bool, optional) – Display output in machine readable format.

  • row_count (bool, optional) – Display row count of invalid buildspces table

print_filter_fields()[source]

This method prints filter fields available for buildspec cache. This method implements command buildtest buildspec find --helpfilter

print_format_fields()[source]

This method prints format fields available for buildspec cache. This method implements command buildtest buildspec find --helpformat

print_raw_filter_fields()[source]

This method prints the raw filter fields available for buildspec cache. This method implements command buildtest buildspec find --filterfields

print_raw_format_fields()[source]

This method prints the raw format fields available for buildspec cache. This method implements command buildtest buildspec find --formatfields

print_paths()[source]

This method print buildspec paths, this implements command buildtest buildspec find --paths

buildtest.cli.buildspec.edit_buildspec_test(test_names, configuration, editor)[source]

Open a list of test names in editor mode defined by EDITOR environment otherwise resort to vim. This method will search for buildspec cache and find path to buildspec file corresponding to test name and open file in editor. If multiple test are specified via buildtest buildspec edit-test then each file will be open and upon closing file, the next file will be open for edit until all files are written.

Parameters:
  • test_names (list) – A list of test names to open in editor

  • configuration (buildtest.config.SiteConfiguration) – An instance of SiteConfiguration class

  • editor (str) – Path to editor to use when opening file

buildtest.cli.buildspec.edit_buildspec_file(buildspecs, configuration, editor)[source]

Open buildspec in editor and validate buildspec with parser. This method is invoked by command buildtest buildspec edit-file.

Parameters:
  • buildspec (str) – Path to buildspec file to edit

  • configuration (buildtest.config.SiteConfiguration) – An instance of SiteConfiguration class

  • editor (str) – Path to editor to use when opening file

buildtest.cli.buildspec.is_test_name_in_cache(test_name, cache)[source]

Check if a test name is in the cache.

Parameters:
  • test_name (str) – The test name to check.

  • cache (BuildspecCache) – An instance of BuildspecCache used for storing the buildspec cache

Returns:

True if the test name is in the cache, False otherwise.

Return type:

bool

buildtest.cli.buildspec.show_buildspecs(test_names, configuration, theme=None)[source]

This is the entry point for buildtest buildspec show command which will print content of buildspec based on name of test.

Parameters:
buildtest.cli.buildspec.show_tests_by_status(configuration, status, test_names=None, report_file=None, theme=None)[source]

This method which will print content of buildspec given test names for a desired status. The status argument can be FAIL or PASS which will be used to search in report file and extract test names based on status and then determine the corresponding buildspec that generated the test.

Parameters:
buildtest.cli.buildspec.show_failed_buildspecs(configuration, test_names=None, report_file=None, theme=None)[source]

This is the entry point for buildtest buildspec show-fail command which will print content of buildspec on name of all failed tests if a list of test names are not specified

Parameters:
buildtest.cli.buildspec.handle_exception(buildspec, exception)[source]

Handle exceptions during buildspec validation.

buildtest.cli.buildspec.buildspec_validate_command(configuration, buildspecs=None, excluded_buildspecs=None, tags=None, executors=None, name=None)[source]

Entry point for buildtest buildspec validate. This method is responsible for discovering buildspec with same options used for building buildspecs that includes --buildspec, --exclude, --tag, and --executor. Upon discovery we pass each buildspec to BuildspecParser class to validate buildspec and report any errors during validation which is raised as exceptions.

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – An instance of SiteConfiguration class which is the loaded buildtest configuration used for validating the buildspecs.

  • buildspecs (list, optional) – List of paths to buildspec file which can be a file or directory. This option is specified via buildtest buildspec validate --buildspec

  • excluded_buildspecs (list, optional) – List of excluded buildspecs which can be a file or directory. This option is specified via buildtest buildspec validate --exclude

  • tags (list, optional) – List of tag names to search for buildspec to validate. This option is specified via buildtest buildspec validate --tag

  • executors (list, optional) – List of executor names to search for buildspecs to validate. This option is specified via buildtest buildspec validate --executor

  • name (str, optional) – Name of test to validate. This option is specified via buildtest buildspec validate --name

buildtest.cli.buildspec.summarize_buildspec_cache(pager, configuration, color=None)[source]

This is a helper method used for printing output of buildtest buildspec summary with and without pagination

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – instance of type SiteConfiguration

  • pager (bool) – Boolean control output of summary with paging

  • color (str, optional) – An instance of str, color that the summary should be printed in

buildtest.cli.buildspec.summary_print(configuration, color=None)[source]

This method will print summary of buildspec cache file. This method is the core logic used for showing output of command buildtest buildspec summary.

Parameters:
buildtest.cli.buildspec.buildspec_maintainers(configuration, breakdown=None, terse=None, header=None, color=None, name=None, row_count=None, count=None, pager=None)[source]

Entry point for buildtest buildspec maintainers command.

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – instance of type SiteConfiguration

  • terse (bool, optional) – Print in terse mode

  • header (bool, optional) – If True disable printing of headers

  • color (bool, optional) – Print output of table with selected color

  • name (str, optional) – List all buildspecs corresponding to maintainer name. This command is specified via buildtest buildspec maintainers find <name>

  • row_count (bool, opotional) – Print row count of the maintainer table. This command is specified via buildtest --row-count buildspec maintainers -l

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec maintainers --count

  • pager (bool, optional) – Enable paging of output

buildtest.cli.buildspec.buildspec_find(args, configuration)[source]

Entry point for buildtest buildspec find command

Parameters:
buildtest.cli.buildspec.open_buildspec_in_editor(buildspec, editor)[source]

Open a buildspec in the specified editor and print a message.

Parameters:
  • buildspec (str) – The path to the buildspec file to open.

  • editor (str) – The editor to open the buildspec file in.

buildtest.cli.buildspec.validate_buildspec(buildspec, configuration)[source]

Validate a buildspec with JSON Schema and print whether it is valid or not.

Parameters: