zopkio package

Submodules

zopkio.adhoc_deployer module

class zopkio.adhoc_deployer.SSHDeployer(service_name, configs=None)

Bases: zopkio.deployer.Deployer

A simple deployer that copies an executable to the remote host and runs it

get_host(unique_id)

Gets the host of the process with unique_id. If the deployer does not know of a process with unique_id then it should return a value of SOME_SENTINAL_VALUE

Parameter unique_id:  the name of the process

:raises NameError if the name is not valid process

get_pid(unique_id, configs=None)

Gets the pid of the process with unique_id. If the deployer does not know of a process with unique_id then it should return a value of constants.PROCESS_NOT_RUNNING_PID

get_processes()

Gets all processes that have been started by this deployer

Returns:A list of Processes

install(unique_id, configs=None)

Copies the executable to the remote machine under install path. Inspects the configs for the possible keys ‘hostname’: the host to install on ‘install_path’: the location on the remote host ‘executable’: the executable to copy ‘no_copy’: if this config is passed in and true then this method will not copy the executable assuming that it is already installed ‘post_install_cmds’: an optional list of commands that should be executed on the remote machine after the

executable has been installed. If no_copy is set to true, then the post install commands will not be run.

If the unique_id is already installed on a different host, this will perform the cleanup action first. If either ‘install_path’ or ‘executable’ are provided the new value will become the default.

Parameters:

• unique_id –
• configs –

Returns:

kill_all_process()

Terminates all the running processes. By default it is set to false. Users can set to true in config once the method to get_pid is done deterministically either using pid_file or an accurate keyword

start(unique_id, configs=None)

Start the service. If unique_id has already been installed the deployer will start the service on that host. Otherwise this will call install with the configs. Within the context of this function, only four configs are considered ‘start_command’: the command to run (if provided will replace the default) ‘args’: a list of args that can be passed to the command ‘sync’: if the command is synchronous or asynchronous defaults to asynchronous ‘delay’: a delay in seconds that might be needed regardless of whether the command returns before the service can be started

Parameters:

• unique_id –
• configs –

Returns:

if the command is executed synchronously return the underlying paramiko channel which can be used to get the stdout

otherwise return the triple stdin, stdout, stderr

stop(unique_id, configs=None)

Stop the service. If the deployer has not started a service with`unique_id` the deployer will raise an Exception There are two configs that will be considered: ‘terminate_only’: if this config is passed in then this method is the same as terminate(unique_id) (this is also the behavior if stop_command is None and not overridden) ‘stop_command’: overrides the default stop_command

Parameters:

• unique_id –
• configs –

Returns:

uninstall(unique_id, configs=None)

uninstall the service. If the deployer has not started a service with unique_id this will raise a DeploymentError. This considers one config: ‘additional_directories’: a list of directories to remove in addition to those provided in the constructor plus

the install path. This will update the directories to remove but does not override it

Parameters:

• unique_id –
• configs –

Returns:

zopkio.configobj module

class zopkio.configobj.Config(name, mapping)

Bases: object

Structure used to stores information about a configuration during runtime

zopkio.constants module

Constants that are used in multiple classes

zopkio.deployer module

class zopkio.deployer.Deployer

Bases: object

Abstract class specifying required contract for a Deployer

A deployer implements both the basic contracts for deployment as well as keeping track of the state of deployed applications

deploy(unique_id, configs=None)

Deploys the service to the host. This should at least perform the same actions as install and start but may perform additional tasks as needed.

Parameter unique_id:  the name of the process Parameter configs:  a mao of configs the deployer may use to modify the deployment

fetch_logs(unique_id, logs, directory, pattern='')

Copies logs from the remote host that the process is running on to the provided directory

:Parameter unique_id the unique_id of the process in question :Parameter logs a list of logs given by absolute path from the remote host :Parameter directory the local directory to store the copied logs :Parameter pattern a pattern to apply to files to restrict the set of logs copied

fetch_logs_from_host(hostname, install_path, prefix, logs, directory, pattern)

Copies logs from any host on the specified install path

:Parameter hostname the remote host from where we need to fetch the logs :Parameter install_path path where the app is installed :Parameter prefix prefix used to copy logs. Generall the unique_id of process :Parameter logs a list of logs given by absolute path from the remote host :Parameter directory the local directory to store the copied logs :Parameter pattern a pattern to apply to files to restrict the set of logs copied

get_host(unique_id)

Gets the host of the process with unique_id. If the deployer does not know of a process with unique_id then it should return a value of SOME_SENTINAL_VALUE

Parameter unique_id:  the name of the process

get_logs(unique_id, logs, directory, pattern='')

deprecated name for fetch_logs

get_pid(unique_id, configs=None)

Gets the pid of the process with unique_id. If the deployer does not know of a process with unique_id then it should return a value of constants.PROCESS_NOT_RUNNING_PID If no pid_file/pid_keyword is specified a generic grep of ps aux command is executed on remote machine based on process parameters which may not be reliable if more process are running with similar name

Parameter unique_id:  the name of the process

get_processes()

Gets all processes that have been started by this deployer

Returns:An iteratable of Processes

hangup(unique_id, configs=None)

Issue a signal to hangup the specified process

Parameter unique_id:  the name of the process

hard_bounce(unique_id, configs=None)

Performs a hard bounce (kill and start) for the specified process

Parameter unique_id:  the name of the process

install(unique_id, configs=None)

Install the service. The deployer should use the configs to determine where to install the host

Parameter unique_id:  the name of the process Parameter configs:  a map of configs the deployer may use to determine where to install the service and any modifications

kill(unique_id, configs=None)

Issues a kill -9 to the specified process calls the deployers get_pid function for the process. If no pid_file/pid_keyword is specified a generic grep of ps aux command is executed on remote machine based on process parameters which may not be reliable if more process are running with similar name

Parameter unique_id:  the name of the process

kill_all_process()

Terminates all the running processes

pause(unique_id, configs=None)

Issues a sigstop for the specified process

Parameter unique_id:  the name of the process

resume(unique_id, configs=None)

Issues a sigcont for the specified process

Parameter unique_id:  the name of the process

sleep(unique_id, delay, configs=None)

Pauses the process for the specified delay and then resumes it

Parameter unique_id:  the name of the process Parameter delay:  delay time in seconds

soft_bounce(unique_id, configs=None)

Performs a soft bounce (stop and start) for the specified process

Parameter unique_id:  the name of the process

start(unique_id, configs=None)

Start the service. If unique_id has already been installed it is expected that the service is started on the host specified by the previous instance of install. Otherwise the deployer may use the configs to determine where to install the process.

Parameter unique_id:  the name of the process Parameter configs:  a map of configs the deployer may use to modify the start

stop(unique_id, configs=None)

Stop the service. If the deployer has not started a service with unique_id the deployer may take any action.

Parameter unique_id:  the name of the process Parameter configs:  a map of configs the deployer may use to modify the stop

terminate(unique_id, configs=None)

Issues a kill -15 to the specified process

Parameter unique_id:  the name of the process

undeploy(unique_id, configs=None)

Undeploys the service. This should at least perform the same actions as stop and uninstall but may perform additional tasks as needed.

Parameter unique_id:  the name of the process Parameter configs:  a map of configs the deployer may use

uninstall(unique_id, configs=None)

uninstall the service. If the deployer has not started a service with unique_id the deployer may take any action. The uninstall is assumed to clean any directory the service touches not merely the locations that the service is installed to

Parameter unique_id:  the name of the process Parameter configs:  a map of configs the deployer may use

class zopkio.deployer.Process(unique_id, servicename, hostname, install_path)

Bases: object

This is an abstraction of a service installed on a host

zopkio.error_messages module

zopkio.recipes module

zopkio.recipes.test_kill_random_deployer_process(deployer_list, deployer_process_dict, deployer_restart_func_dict={}, deployer_verify_recovery_dict={}, deployer_timeout_dict={})

A test recipe to select a random deployer and kill one of its process.If no process is present in list then all its process will be killed :param deployer_list: List of deployer from which we want to select one and kills its process :param deployer_process_dict: dictionary with list of process ids per deployer from which we need to kill one randomly. :param deployer_restart_func_dict : dictionary with key as deployer and value as dict of restart commands if any for list of process. :param deployer_verify_recovery_dict: dictionary with key as deployer and value as verify function per process to verify if the system was restored correctly. :param deployer_timeout_dict: dictionary with key as deployer and value as optional timeout parameter in seconds per process specified has dictionary.

zopkio.recipes.test_kill_recovery(kill_deployer, kill_deployer_processes, restart_func_dict={}, verify_recovery_dict={}, timeout_dict={})

A test recipe to kill a component in distributed system and verify system recovery once its brought back. :param kill_deployer: The deployer one of whose process needs to be killed :param kill_deployer_processes: list of process ids from which we need to kill one randomly. :param restart_func_dict : dictionary with restart commands if any for list of process. :param verify_recovery_dict: Verify function per process to verify if the system was restored correctly.Wait till this function returns true :param timeout_dict: optional timeout parameter in seconds per process specified has dictionary. If the system did not recover within this time then error out

zopkio.remote_host_helper module

exception zopkio.remote_host_helper.DeploymentError(msg)

Bases: exceptions.Exception

Represents an exception occurring in the deployment module

Attributes:

msg – explanation of the error

exception zopkio.remote_host_helper.ParamikoError(msg, errors)

Bases: zopkio.remote_host_helper.DeploymentError

Represents an exception if a command Paramiko tries to execute fails

Attributes:

msg – explanation of the error errors – a list of lines representing the output to stderr by paramiko

zopkio.remote_host_helper.better_exec_command(ssh, command, msg)

Uses paramiko to execute a command but handles failure by raising a ParamikoError if the command fails. Note that unlike paramiko.SSHClient.exec_command this is not asynchronous because we wait until the exit status is known

Parameter ssh:a paramiko SSH Client Parameter command:  the command to execute Parameter msg:message to print on failure

:Returns (paramiko.Channel)

the underlying channel so that the caller can extract stdout or send to stdin

Raises SSHException:  if paramiko would raise an SSHException Raises ParamikoError:  if the command produces output to stderr

zopkio.remote_host_helper.build_os_environment_string(env)

Creates a string of the form export key0=value0;export key1=value1;... for use in running commands with the specified environment

Parameter variables:  a dictionay of environmental variables Returns string:a string that can be prepended to a command to run the command with

the environmental variables set

zopkio.remote_host_helper.copy_dir(ftp, filename, outputdir, prefix, pattern='')

Recursively copy a directory flattens the output into a single directory but prefixes the files with the path from the original input directory :param ftp: :param filename: :param outputdir: :param prefix: :param pattern: a regex pattern for files to match (by default matches everything) :return:

zopkio.remote_host_helper.exec_with_env(ssh, command, msg='', env={}, **kwargs)

Parameters:

• ssh –
• command –
• msg –
• env –
• synch –

Returns:

zopkio.remote_host_helper.get_remote_session(*args, **kwds)

zopkio.remote_host_helper.get_remote_session_with_environment(*args, **kwds)

zopkio.remote_host_helper.get_sftp_client(*args, **kwds)

zopkio.remote_host_helper.get_ssh_client(*args, **kwds)

zopkio.remote_host_helper.log_output(chan)

logs the output from a remote command the input should be an open channel in the case of synchronous better_exec_command otherwise this will not log anything and simply return to the caller :param chan: :return:

zopkio.remote_host_helper.open_remote_file(*args, **kwds)

Parameters:

• hostname –
• filename –

Returns:

zopkio.remote_host_helper.sshclient()

zopkio.reporter module

Class used to generate the report.

class zopkio.reporter.Reporter(report_name, output_dir, logs_dir, naarad_dir)

Bases: object

Class that converts the aggregated output into a user-friendly web page.

generate()

Generates the report

get_config_to_test_names_map()

get_report_location()

Returns the filename of the landing page

zopkio.results_collector module

class zopkio.results_collector.Results(config, tests)

Bases: object

class zopkio.results_collector.ResultsCollector

Bases: object

Provides a way to store intermediate results with fast access to individual results. Also provides common aggregation functions for the results.

collect(config, tests)

count_all_tests()

Returns:total number of tests ran under all configs

count_all_tests_with_result(result_type)

Count total number of tests with a certain result :param result_type: constants.PASSED, constants.FAILED, constants.SKIPPED :return: the number of tests where test.result == result_type

count_tests(config_name)

Parameters:config_name – Returns:total number of tests ran under config_name

count_tests_with_result(config_name, result_type)

Count the number of tests of a configuration with a certain result :param config_name: name of the configuration :param result_type: constants.PASSED, constants.FAILED, constants.SKIPPED :return: the number of tests in config_name where test.result == result_type

get_config_end_time(config_name)

get_config_exec_time(config_name)

get_config_names()

get_config_result(config_name)

get_config_start_time(config_name)

get_summary_end_time()

Returns:end time of test

get_summary_start_time()

Returns:start time of test

get_test_end_time(config_name, test_name)

get_test_exec_time(config_name, test_name)

get_test_names(config_name)

get_test_result(config_name, test_name)

get_test_results(config_name)

get_test_start_time(config_name, test_name)

get_total_config_exec_time()

Returns:total execution time of all configurations

zopkio.runtime module

zopkio.runtime.get_active_config(config_option, default=None)

gets the config value associated with the config_option or returns an empty string if the config is not found :param config_option: :param default: if not None, will be used :return: value of config. If key is not in config, then default will be used if default is not set to None. Otherwise, KeyError is thrown.

zopkio.runtime.get_active_config_name()

zopkio.runtime.get_active_test_end_time(test_name)

zopkio.runtime.get_active_test_metrics(test_name)

zopkio.runtime.get_active_test_start_time(test_name)

zopkio.runtime.get_collector()

Simulates a singleton collector that can be used globally :return: results_collector instantiated with the runtime module

zopkio.runtime.get_deployer(service_name)

Gets the deployer associated with the service :param service_name: :return:

zopkio.runtime.get_deployers()

Returns all known deployers, primarily used internally to handle cleanup and log collection, but available for other use :return:

zopkio.runtime.get_init_time()

zopkio.runtime.get_machine(machine_name)

gets the physical machine associated with the name. By default return localhost :param machine_name: :return:

zopkio.runtime.get_output_dir()

zopkio.runtime.get_password()

Returns:the password of the user (needed for lid)

zopkio.runtime.get_reports_dir()

zopkio.runtime.get_username()

Returns:the username of the user running the process (needed for lid)

zopkio.runtime.remove_deployer(service_name)

Remove the deployer with the given name, if it exists :param service_name: name of deployer to remove

zopkio.runtime.reset_all()

Clear relevant globals to start fresh :return:

zopkio.runtime.reset_collector()

Reset the global collector this is used for testing

zopkio.runtime.reset_deployers()

Clear all added deployers

zopkio.runtime.set_active_config(config)

Private function to set the config mapping should only be called from the main file :param configs: :return:

zopkio.runtime.set_active_tests(tests)

zopkio.runtime.set_deployer(service_name, deployer)

Specifies the deployer associated with a particular service :param service_name: :param deployer: :return:

zopkio.runtime.set_init_time(time)

zopkio.runtime.set_machines(machines)

Private function to set the machine mapping should only be called from the main file :param machines: :return:

zopkio.runtime.set_output_dir(output_dir)

zopkio.runtime.set_user(username, password)

Private function to set the username and password should only be called from the main function :param username: :param password: :return:

zopkio.test_runner module

Runs tests.

class zopkio.test_runner.FailureHandler(failures_before_abort=None)

Bases: object

Maintains failure state to manage what to do after a non-test failure occurs

get_abort_status()

notify_failure()

notify_success()

class zopkio.test_runner.TestRunner(*args, **kwargs)

Bases: object

Runs tests with the information given in the testfile

compute_total_iterations_per_test()

Factor in loop_all_tests config into iteration count of each test Each test has an tests_iteration associated with them from the test module. The loop_all_tests is set in config that repeats the entire suite after each tests necessary iterations is repeated

Returns:

fail_count()

get_logs_dir()

get_output_dir()

run()

This is the main executable function that will run the test

set_logs_dir(path)

success_count()

zopkio.test_runner_helper module

Delegate for non-execution tasks for TestRunner

zopkio.test_runner_helper.directory_setup(testfile, perf_module, configs)

Sets up the output directories.

Parameters:testfile – the main testfile used in run_test(); only used here for its file name Returns:dict with keys [“report_name”, “report_dir”, “logs_dir”]

zopkio.test_runner_helper.get_modules(testfile, tests_to_run, config_overrides)

Gets modules and objects required to run tests

Parameters:

• testfile –
• tests_to_run –
• config_overrides –

Returns:

zopkio.test_runner_helper.load_configs_from_directory(config_dir, overrides)

Returns a master configuration object and a list of configuration objects

Parameters:

• config_dir – the directory where the configuration files are located
• overrides – mapping of the command line overrides

zopkio.test_utils module

zopkio.test_utils.get_log_for_test(test_name, log_path, dt_format)

Gets the portion of the log file relevant to the test (i.e lies between the start and end times of the test). It is assumed that every line in the log file starts with a datetime following dtformat. :param test_name: the test name :param log_path: the absolute path to the log file :param dt_format: the format of the datetime in the log file. This could simply be an example datetime because

only the word count matters

zopkio.test_utils.start_threads_and_join(commands)

zopkio.testobj module

class zopkio.testobj.Test(name, function, **kwargs)

Bases: object

Structure used to store information about a test during runtime

reset()

Reset to a ‘clean’ state, i.e all test data is reset and only the name and functions are kept

zopkio.utils module

Utilities class provides general-use functions for all modules

zopkio.utils.check_dir_with_exception(dirname)

Checks if the directory exists; if not, throw an exception

zopkio.utils.check_file_with_exception(filename)

Checks if the file exists; if not, throw an exception

zopkio.utils.check_testfile_dir_structure(filename)

Checks if the test file has correct directory structure for importing as module Makes sure there is no directory with same testfile name to cause conflict

zopkio.utils.load_module(filename)

Loads a module by filename

zopkio.utils.make_machine_mapping(machine_list)

Convert the machine list argument from a list of names into a mapping of logical names to physical hosts. This is similar to the _parse_configs function but separated to provide the opportunity for extension and additional checking of machine access

zopkio.utils.makedirs(path)

Makes directories without raising an error if the directory already exists :param path: the path of the directory :return:

zopkio.utils.parse_config_file(config_file_path)

Parse a configuration file. Currently only supports .json, .py and properties separated by ‘=’ :param config_file_path: :return: a dict of the configuration properties

zopkio.utils.parse_config_list(config_list)

Parse a list of configuration properties separated by ‘=’

Module contents

Zopkio test framework