API Documentation

This part of the documentation lists the full API reference of all public classes and functions.

Walker

class altwalker.walker.Walker(planner, executor, reporter)

Coordinates the execution of a test asking a Planner for the next step, executing the step using an Executor, if needed passing a dict object to the test code, and reporting the progress using a Reporter.

run()

Run tests.

property status

The status of the current run.

Examples

You can run the tests using the Walker.run() method:

walker = Walker(...)
walker.run()

Or iterating over a Walker object:

walker = Walker(...)
for step in walker:
    # do something with the step
altwalker.walker.create_walker(planner, executor, reporter=None)

Create a Walker object, and if no reporter is provided initialize it with the default options.

Planner

The role of a Planner is to determine the next step to be executed by the Executor.

There are two Planners:

  • OnlinePlanner:

    Uses GraphWalker online mode to generate the test path.

    This method allows the test code to directly interact with GraphWalker and modify the model data. A dictionary with model data will be passed as a the first argument to any method/function form the test code by Walker class.

  • OfflinePlanner:

    Uses a sequence of steps to generate the test path.

    The sequence of path can be generated using the offline() function.

class altwalker.planner.OnlinePlanner(client, service=None)

Plan a path using the GraphWalker REST service and client.

The path generation is done at run-time, one step at a time, using the GraphWalker REST Service. This adds a bit of complexity, but the advantages is that you can interact with the graph data using get_data() and set_data() methods.

Note

The planner requires the GraphWalker service to be started with the verbouse flag.

fail(message)

Will mark the step as a failure and the current model.

get_data()

Get the current data values for the current model.

get_next()

Get the next step in the current path.

get_statistics()

Return the statistics for the current path.

has_next()

Check if there is an available step in the current path.

kill()

Stop the GraphWalkerService process if needed.

load(models)

Load the module(s) and reset the execution and the statistics.

restart()

Will rests the execution and the statistics.

set_data(key, value)

Set data in the current model.

class altwalker.planner.OfflinePlanner(path)

Plan a path from a list of steps.

Parameters

path – A sequence of steps. A step is a dict containing a name and a modelName.

fail(message)

This method does nothing.

get_data()

Is not supported and will return an empty dict.

get_next()

Get the next element form the path.

Returns

A dictionary containing the step id, name and model:

{
    "id": step_id,
    "name": step_name,
    "modelName": model_name
}

Return type

dict

get_statistics()

This method returns an empty dict.

has_next()

Check if there are more element in path.

kill()

This method does nothing.

load(models)

This method does nothing.

property path

Return the path, the original sequence of steps.

restart()

Will rests the executed steps sequence and the statistics.

set_data(key, value)

Is not supported and will throw a warning.

property steps

Return a sequence of executed steps.

altwalker.planner.create_planner(models=None, steps=None, host=None, port=8887, start_element=None, verbose=False, unvisited=False, blocked=False)

Create a planner object.

Parameters
  • models (list) – A sequence of tuples containing the model_path and the stop_condition.

  • steps (list) – If step is set will create a OfflinePlanner.

  • host (str) – If the host is set will not start a GraphWalker service (e.g. 127.0.0.1).

  • port (int) – The port of the GraphWalker service, to start on or to listen (e.g. 8887).

  • start_element (str) – A starting element for the first model.

  • verbose (bool) – If set will start the GraphWalker service with the verbose flag.

  • unvisited (bool) – If set will start the GraphWalker service with the unvisited flag.

  • blocked (bool) – If set will start the GraphWalker service with the blocked flag.

Note

If the host or steps parameters are set models, verbose, unvisited and blocked have no effect.

Note

If you start a GraphWalker service start it with the verbouse flag.

Executor

The role of the executor is to handle the test execution. Every executor should have all the methods form the Executor.

class altwalker.executor.Executor

An abstract class that defines the executor protocol.

abstract execute_step(model_name, name, data=None)

Execute a step from a model.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

  • data (dict) – The current graph data.

Note

If model_name is None the step is a fixture.

Returns

The graph data, the output of the step, and the error message with the trace if an error occurred:

{
    "output": "",
    "data": {},
    "error": {
        "message": "",
        "trace": ""
    }
}

If no error occurred the error key can be omitted or set to None.

If the graph data is not used or modified the data key can be omitted or set to None.

Return type

dict

abstract has_model(model_name)

Return True if the model is available.

Parameters

model_name (str) – The name of the model.

Returns

True if the model is available, False otherwise.

Return type

bool

abstract has_step(model_name, name)

Return True if the step from the model is available.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

Note

If model_name is None the step is a fixture.

Returns

True if the step from the model is available, False otherwise.

Return type

bool

abstract kill()

Cleanup resources and kill processes if needed.

abstract load(path)

Load the test code from a path.

Parameters

path (str) – The path to the test code.

abstract reset()

Reset the current execution.

class altwalker.executor.HttpExecutor(url='http://localhost:5000')

Http client for an executor service.

Parameters

url (str) – The URL of the executor service (e.g http://localhost:5000).

has_model(name)

Makes a GET request at /hasModel?modelName=<model_name>.

Parameters

model_name (str) – The name of the model.

Returns

True if the model is available, False otherwise.

Return type

bool

has_step(model_name, name)

Makes a GET request at /hasStep?modelName=<model_name>&name=<name>.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

Returns

True if the step from the model is available, False otherwise.

Return type

bool

execute_step(model_name, name, data=None)

Makes a POST request at /executeStep?modelName=<model_name>&name=<name>.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

  • data (dict) – The current graph data.

Returns

The graph data, the output of the step, and the error message with the trace if an error occurred:

{
    "output": "",
    "data: {},
    "error": {
        "message": "",
        "trace": ""
    }
}

Return type

dict

reset()

Makes an PUT at /reset.

kill()

This method does nothing.

class altwalker.executor.PythonExecutor(module=None)

Execute methods or functions from a model like object.

execute_step(model_name, name, data=None)

Execute a step from a model.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

  • data (dict) – The current graph data.

Note

If model_name is None the step is a fixture.

Returns

A dict containing the graph data, the output of the step, the result returned by the step method, and the error message with the trace if an error occurred:

{
    "output": "",
    "data": {},
    "result": Any,
    "error": {
        "message": "",
        "trace": ""
    }
}

If no error occurred the error key can be omitted or set to None.

If the graph data is not used or modified the data key can be omitted or set to None.

has_model(name)

Check if the module has a class named name.

Parameters

name – The name of the class

Returns

True if the module has a class named name, False otherwise.

Return type

bool

has_step(model_name, name)

Check if the module has a class named model_name with a method named.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

Note

If model_name is None the step is a fixture.

Returns

True if the step from the model is available, False otherwise.

Return type

bool

kill()

This method does nothing.

load(path)

Load the test code from a path and reset the current execution.

reset()

Reset the current execution.

class altwalker.executor.DotnetExecutor(path, url='http://localhost:5000/')

Starts a C#/.NET executor service, and allows you to interact with it.

Parameters
  • path – The path of the console application project, dll or exe, that starts an ExecutorService.

  • url – The url for the service to listen (e.g. http://localhost:5000/).

execute_step(model_name, name, data=None)

Makes a POST request at /executeStep?modelName=<model_name>&name=<name>.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

  • data (dict) – The current graph data.

Returns

The graph data, the output of the step, and the error message with the trace if an error occurred:

{
    "output": "",
    "data: {},
    "error": {
        "message": "",
        "trace": ""
    }
}

Return type

dict

has_model(name)

Makes a GET request at /hasModel?modelName=<model_name>.

Parameters

model_name (str) – The name of the model.

Returns

True if the model is available, False otherwise.

Return type

bool

has_step(model_name, name)

Makes a GET request at /hasStep?modelName=<model_name>&name=<name>.

Parameters
  • model_name (str) – The name of the model.

  • name (str) – The name of the step.

Returns

True if the step from the model is available, False otherwise.

Return type

bool

kill()

Kill the executor service.

load(path)

Kill the executor service and start a new one with the given path.

reset()

Makes an PUT at /reset.

altwalker.executor.create_http_executor(path, *args, url='http://localhost:5000/', **kwargs)

Creates a HTTP executor.

Parameters
Returns

A HTTP executor.

Return type

HttpExecutor

altwalker.executor.create_python_executor(path, *args, **kwargs)

Creates a Python executor.

Parameters

path – The path to the tests.

Returns

A Python executor.

Return type

PythonExecutor

altwalker.executor.create_dotnet_executor(path, *args, url='http://localhost:5000/', **kwargs)

Creates a C#/.NET executor.

Parameters
Returns

A C#/.NET executor.

Return type

DotnetExecutor

altwalker.executor.create_executor(path, executor_type, *args, url='http://localhost:5000/', **kwargs)

Creates an executor.

Parameters
  • path – The path to the tests.

  • executor_type – The type of the executor (e.g. http, python, dotnet).

  • url – The url for the executor service (e.g. http://localhost:5000/).

Raises

AltWalkerException – If the executor_type is not supported.

Reporter

The role of the reporter is to report the results of a test run, a reporter method is called by the Walker for different events:

  • start() - called at the beginning of each run.

  • end() - called at the end of each run.

  • step_start() - called before executing each step.

  • step_end() - called after executing each step.

  • report() - it should return a report if the reporter generates on (e.g. the PrintReporter or FileReporter don’t generate any report, they only log data). It’s not called by the Walker.

Every reporter should have all this methods, you can inherit them from Reporter and overwrite only the methods you want.

class altwalker.reporter.Reporter

The default reporter.

This reporter does not emit any output. It is essentially a ‘no-op’ reporter for use.

_log(string)

This method does nothing.

end(message=None, statistics=None, status=None)

Report the end of a run.

Parameters

message (str) – A message.

error(step, message, trace=None)

Report an unexpected error.

Parameters
  • step (dict) – The step executed when the error occurred.

  • message (str) – The message of the error.

  • trace (str) – The traceback.

report()

Return an report for the run, or None if the reporter doesn’t have a report.

Returns

This reporter doesn’t have a report.

Return type

None

start(message=None)

Report the start of a run.

Parameters

message (str) – A message.

step_end(step, step_result)

Report the result of the step execution.

Parameters
  • step (dict) – The step just executed.

  • step_result (dict) – The result of the step.

step_start(step)

Report the starting execution of a step.

Parameters

step (dict) – The step that will be executed next.

class altwalker.reporter.Reporting

This reporter combines a list of reporters into a singe one, by delegating the calls to every reporter from it’s list.

end(message=None, statistics=None, status=None)

Report the end of a run on all reporters.

Parameters

message (str) – A message.

error(step, message, trace=None)

Report an unexpected error on all reporters.

Parameters
  • step (dict) – The step executed when the error occurred.

  • message (str) – The message of the error.

  • trace (str) – The traceback.

register(key, reporter)

Register a reporter.

Parameters
  • key (str) – A key to identify the reporter.

  • reporter (Reporter) – A reporter.

Raises

ValueError – If a reporter with the same key is already registered.

report()

Returns the reports from all registered reporters.

Returns

Containing all the reports from all the register reports.

Return type

dict

start(message=None)

Report the start of a run on all reporters.

Parameters

message (str) – A message.

step_end(step, step_result)

Report the result of the step execution on all reporters.

Parameters
  • step (dict) – The step just executed.

  • step_result (dict) – The result of the step.

step_start(step)

Report the starting execution of a step on all reporters.

Parameters

step (dict) – The step that will be executed next.

unregister(key)

Unregister a reporter.

Parameters

key (str) – A key of a registered reporter.

Raises

KeyError – If no reporter with the given key was registered.

class altwalker.reporter.FileReporter(file)

This reporter outputs to a file.

Parameters

file (str) – A path to a file to log the output.

Note

If the path already exists the reporter will overwrite the content.

end(message=None, statistics=None, status=None)

Report the end of a run.

Parameters

message (str) – A message.

error(step, message, trace=None)

Report an unexpected error.

Parameters
  • step (dict) – The step executed when the error occurred.

  • message (str) – The message of the error.

  • trace (str) – The traceback.

report()

Return an report for the run, or None if the reporter doesn’t have a report.

Returns

This reporter doesn’t have a report.

Return type

None

start(message=None)

Report the start of a run.

Parameters

message (str) – A message.

step_end(step, step_result)

Report the result of the step execution.

Parameters
  • step (dict) – The step just executed.

  • step_result (dict) – The result of the step.

step_start(step)

Report the starting execution of a step.

Parameters

step (dict) – The step that will be executed next.

class altwalker.reporter.ClickReporter

This reporter outputs using the click.echo() function.

_log(string)

Prints the string using the click.echo() function.

end(message=None, statistics=None, status=None)

Report the end of a run.

Parameters

message (str) – A message.

error(step, message, trace=None)

Report an unexpected error.

Parameters
  • step (dict) – The step executed when the error occurred.

  • message (str) – The message of the error.

  • trace (str) – The traceback.

report()

Return an report for the run, or None if the reporter doesn’t have a report.

Returns

This reporter doesn’t have a report.

Return type

None

start(message=None)

Report the start of a run.

Parameters

message (str) – A message.

step_end(step, step_result)

Report the result of the step execution.

Parameters
  • step (dict) – The step just executed.

  • step_result (dict) – The result of the step.

step_start(step)

Report the starting execution of a step.

Parameters

step (dict) – The step that will be executed next.

class altwalker.reporter.PathReporter(file='path.json', verbose=False)

This reporter keeps a list of all execute steps (without fixtures).

Parameters
  • file (str) – A path to a file to log execution path.

  • verbose (bool) – Will print more details to stdout.

Note

If the path already exists the reporter will overwrite the content.

_log(string)

This method does nothing.

end(message=None, statistics=None, status=None)

Report the end of a run.

Parameters

message (str) – A message.

error(step, message, trace=None)

Report an unexpected error.

Parameters
  • step (dict) – The step executed when the error occurred.

  • message (str) – The message of the error.

  • trace (str) – The traceback.

report()

Return a list of all executed steps.

Returns

Containing all executed steps.

Return type

list

start(message=None)

Report the start of a run.

Parameters

message (str) – A message.

step_end(step, step_result)

Save the step in a list, if the step is not a fixture.

step_start(step)

Report the starting execution of a step.

Parameters

step (dict) – The step that will be executed next.

GraphWalker

REST Service

For more informations check out the GraphWalker REST API Documentation.

class altwalker.graphwalker.GraphWalkerService(models=None, port=8887, start_element=None, unvisited=False, blocked=False, output_file='graphwalker-service.log')

Starts and kills a proccess running the GraphWalker REST service.

Will run the GraphWalker online command and start the GraphWalker REST service.

Note

The GraphWalker REST Service is always started with the verbose flag to get the modelName for each step.

Parameters
  • models (list) – A sequence of tuples containing the model_path and the stop_condition.

  • port (int) – Will start the service on the given port.

  • start_element (str) – A starting element for the first model.

  • unvisited (bool) – Will start the service with the unvisited flag set to True.

  • blocked (bool) – Will start the service with the blocked flag set to True.

  • output_file (str) – If set will save the output of the command in a file.

kill()

Send the SIGINT signal to the GraphWalker service to kill the process and free the port.

class altwalker.graphwalker.GraphWalkerClient(host='127.0.0.1', port=8887, verbose=False)

A client for the GraphWalker REST service.

Note

Because the GraphWalker REST service is always started with the verbose flag, the client by default will filter out the data and properties from the output of get_next.

Parameters
  • host (str) – The host address of the GraphWalker REST service.

  • port (int) – The port of the GraphWalker REST servie.

  • verbose (bool) – If set will not filter out the data and properties from the output of get_next.

fail(message)

Marks a fail in the current model.

Makes a PUT request at /fail.

Parameters

message (str) – The error message.

get_data()

Returns the graph data.

Makes a GET request at /getData.

Returns

The graph data.

Return type

dict

get_next()

Returns the next step from the path.

Makes a GET request at /getNext.

Returns

Depending of how the GraphWalker Service was started get_next will return different responses.

  • With the verbose flag:

    {
        "id": step_id,
        "name": step_name,
        "modelName": model_name,
        "data": [],
        "properties": {}
    }
    
  • With the unvisited flag:

    {
        "id": step_id,
        "name": step_name,
        "modelName": model_name,
        "numberOfElements": number_of_element,
        "numberOfUnvisitedElements": number_of_unvisited_elements,
        "unvisitedElements": []
    }
    

Return type

dict

get_statistics()

Returns the statistics for the current session.

Makes a GET request at /getStatistics.

Returns

The statistics.

Return type

dict

has_next()

Returns True if a new step is available. If True, then the fulfillment of the stop conditions has not yet been reached.

Makes a GET request at /hasNext.

Returns

True if a new step is available, False otherwise.

Return type

bool

load(model)

Loads a new model(s) in JSON format.

Make a POST request at /load.

Parameters

model (dict) – The JSON model.

restart()

Reset the currently loaded model(s) to it’s initial state.

Makes a PUT request at /restart.

set_data(key, value)

Sets data in the current model.

Makes a PUT request at /setData.

Parameters
  • key (str) – The key to update.

  • value (str, int, bool) – The value to set.

CLI

For more information check out the GraphWalker CLI Documentation.

altwalker.graphwalker.check(models, blocked=None)

Execute the check command.

Parameters
  • models (list) – A sequence of tuples containing the model_path and the stop_condition.

  • blocked (bool) – Run the command with the blocked flag.

Returns

The output form GraphWalker check.

Return type

str

Raises

GraphWalkerException – If an error occurred while running the command, or the command outputs to stderr.

altwalker.graphwalker.methods(model_path, blocked=False)

Execute the methods command.

Parameters
  • model_path (list) – A path to a model.

  • blocked (bool) – Run the command with the blocked flag.

Returns

A sequence of all unique names of vertices and edges in the model.

Return type

list

Raises

GraphWalkerException – If an error occurred while running the command, or the command outputs to stderr.

altwalker.graphwalker.offline(models, start_element=None, verbose=False, unvisited=False, blocked=None)

Execute the offline command.

Parameters
  • models (list) – A sequence of tuples containing the model_path and the stop_condition.

  • start_element (str) – A starting element for the first model.

  • verbose (bool) – Run the command with the verbose flag.

  • unvisited (bool) – Run the command with the unvisited flag.

  • blocked (bool) – Run the command with the blocked flag.

Returns

A sequence of steps.

Return type

list

Raises

GraphWalkerException – If an error occurred while running the command, or the command outputs to stderr.

Model

A collection of util functions for validating model(s).

altwalker.model.get_models(model_paths)

Combine all models in one json object for GraphWalker REST /load.

Parameters

model_paths – A sequence of path to model files, only .json files.

Returns

A json object containing all models.

Return type

dict

Raises

ValidationException – If the model is not a valid json.

altwalker.model.validate_json_models(model_json)

Validate modules, vertices and edges as python identifiers.

Parameters

model_json (dict) – A models object.

Raises

ValidationException – If the model is not a valid model.

altwalker.model.validate_models(model_paths)

Validate models from a list of paths.

Parameters

model_paths (list) – A sequence of path to model files.

Raises

ValidationException – If the model is not a valid model.

altwalker.model.check_models(models, blocked=False)

Check and analyze the model(s) for issues.

Parameters
  • models – A sequence of tuples containing the model_path and the stop_condition.

  • blocked (bool) – If set to true will filter out elements with the keyword blocked.

Raises

Code

A collection of util functions for validating code against model(s).

altwalker.code.get_methods(model_paths, blocked=False)

Return all required methods for all models.

Parameters
  • model_paths (list) – A sequence of path to model files.

  • blocked (bool) – If set to true will filter out elements with the keyword blocked.

Returns

A dict containing each model name as a key and a list containing its required methods as values.

Return type

dict

altwalker.code.validate_code(executor, methods)

Validate code against a dict of methods.

Parameters
  • executor (Executor) – An executor object.

  • methods (dict) – A dict of methods.

Raises

ValidationException – If the code is not valid.

altwalker.code.verify_code(path, executor, model_paths, url)

Verify test code against the model(s).

Parameters
  • path (str) – The path to the project root.

  • executor (str) – The type of executor.

  • model_paths (list) – A sequence of path to model files.

  • url (str) – The URL of the executor service (e.g http://localhost:5000/).

Raises

Exceptions

Standard Exceptions

exception altwalker.exceptions.GraphWalkerException

An internal exception that signals a GraphWalker error.

exception altwalker.exceptions.AltWalkerException

An internal exception that signals a AltWalker error.

exception altwalker.exceptions.ValidationException

An internal exception that signals a model(s) or test code validation error.

exception altwalker.exceptions.ExecutorException

An internal exception that signals a executor error.

Click Exceptions

This exceptions are used in the cli to handle the exit_code and the display of GraphWalkerException and AltWalkerException.

exception altwalker.exceptions.FailedTestsError

An exception that handles the tests failure in the command line.

exit_code = 1

The exit code for this exception.

exception altwalker.exceptions.GraphWalkerError(message: str)

An exception that handles the display of an GraphWalker error in the command line.

exit_code = 3

The exit code for this exception.

exception altwalker.exceptions.AltWalkerError(message: str)

An exception that handles the display of an AltWalker error in the command line.

exit_code = 4

The exit code for this exception.