API Documentation

Attention

This documentation is deprecated and should no longer be used.

Please, check the new documentation at https://altwalker.github.io/altwalker/, which is being actively maintained.

Also note that all projects related to AltWalker were moved from GitLab to GitHub, you can find the new projects at https://github.com/altwalker.

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

Table of Contents

Walker
Planner
Executor
Reporter
GraphWalker
- REST Service
- CLI
Model
Code
Exceptions
- Standard Exceptions
- Click Exceptions

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

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

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

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

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)

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

GraphWalkerException – If an error is raised by the check command.
ValidationException – If the models are not valid models.

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

GraphWalkerException – If an error is raised by the methods command.
ValidationException – If the model(s) or the code are not a valid.

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.

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.

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.

exit_code = 4: The exit code for this exception.