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.

property status

The status of the current run.

run()

Run tests.

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 sequense 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.

get_next()

Get the next step in the current path.

Step example:

{
    "id": step_id,
    "name": step_name,
    "modelName": model_name
}
kill()

Stop the GraphWalkerService process if needed.

load(models)

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

has_next()

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

get_next()

Get the next step in the current path.

get_data()

Get the current data values for the current model.

set_data(key, value)

Set data in the current model.

restart()

Will rests the execution and the statistics.

fail(message)

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

class altwalker.planner.OfflinePlanner(path)

Plan a path from a list of steps.

Parameters

path – A sequens of steps. A setep is a dict containing a name and a modelName.

Step example:

{
    "name": step_name,
    "modelName": model_name
}
property steps

Return a sequence of executed steps.

property path

Return the path, the original sequence of steps.

has_next()

Check if there are more element in path.

get_next()

Get the next element form the path.

get_data()

Is not supported and will return an empty dict.

set_data(key, value)

Is not supported and will throw a warning.

fail(message)

This method does nothing.

restart()

Will rests the executed steps sequence and the statistics.

get_statistics()

This method returns an empty dict.

kill()

This method does nothing.

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 kill()

Cleanup resources and kill processes if needed.

abstract reset()

Reset the current execution.

abstract load(path)

Load the test code from a path.

Parameters

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

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 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 occured the error key can be omitted or set to None.

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

Return type

dict

class altwalker.executor.HttpExecutor(url)

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.

kill()

This method does nothing.

load(path)

Load the test code from a path.

Parameters

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

reset()

Reset the current execution.

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

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, and the error message with the trace if an error occurred:

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

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

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

class altwalker.executor.DotnetExecutor(path, url)

Starts a .NET executor service, and alows 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/).

load(path)

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

kill()

Kill the executor service.

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

reset()

Makes an PUT at /reset.

altwalker.executor.create_executor(path, type_, url=None)

Creates an executor.

Parameters
  • path – The path to the tests.

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

  • url – The url for the executor service.

Raises

ValueError – If the 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 diffrent 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 inherite 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.

start(message=None)

Report the start of a run.

Parameters

message (str) – A message.

end(message=None)

Report the end of a run.

Parameters

message (str) – A message.

step_start(step)

Report the starting execution of a step.

Parameters

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

step_end(step, result)

Report the result of the step execution.

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

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

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

_log(string)

This method does nothing.

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.

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.

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.

start(message=None)

Report the start of a run on all reporters.

Parameters

message (str) – A message.

end(message=None)

Report the end of a run on all reporters.

Parameters

message (str) – A message.

step_start(step)

Report the starting execution of a step on all reporters.

Parameters

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

step_end(step, result)

Report the result of the step execution on all reporters.

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

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

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.

report()

Returns the reports from all registerd reporters.

Returns

Containing all the reports from all the register reports.

Return type

dict

class altwalker.reporter.PrintReporter

This reporter outputs to stdout using the buildin print() function.

_log(string)

Prints the string using the buildin print() function.

end(message=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, result)

Report the result of the step execution.

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

  • 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.FileReporter(path)

This reporter outputs to a file.

path

A path to a file to log the output.

Type

str

Note

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

end(message=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, result)

Report the result of the step execution.

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

  • 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.

step_end(step, result)

Outputs a colored output for the result of the step execution.

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

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

error(step, message, trace=None)

Outputs a colored output for an unexpected error.

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

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

  • trace (str) – The traceback.

_log(string)

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

end(message=None)

Report the end of a run.

Parameters

message (str) – A message.

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_start(step)

Report the starting execution of a step.

Parameters

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

class altwalker.reporter.PathReporter

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

step_end(step, result)

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

report()

Reutrn a list of all executed steps.

Returns

Containing all executed steps.

Return type

list

_log(string)

This method does nothing.

end(message=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.

start(message=None)

Report the start of a run.

Parameters

message (str) – A message.

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 verbouse flag, the client by default will filter out the data and properties for get_next.

Parameters
  • host (str) – The ip 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 for get_next.

load(model)

Loads a new model(s) in JSON format.

Make a POST request at /load.

Parameters

model (dict) – The JSON model.

has_next()

Returns True if a new step is available. If True, then the fulfilment 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

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_unvisted_elements,
        "unvisitedElements": []
    }
    

Return type

dict

get_data()

Returns the graph data.

Makes a GET request at /getData.

Returns

The graph data.

Return type

dict

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.

restart()

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

Makes a PUT request at /restart.

fail(message)

Marks a fail in the currnet model.

Makes a PUT request at /fail.

Parameters

message (str) – The error message.

get_statistics()

Returns the current statistics of the session.

Makes a GET request at /getStatistcs.

Returns

The statistics.

Return type

dict

CLI

For more informations 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 blcoked flag.

Returns

The output form GraphWalker check.

Return type

str

Raises

GraphWalkerException – If an error occured 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.

  • blcked (bool) – Run the command with the blcoked flag.

Returns

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

Return type

list

Raises

GraphWalkerException – If an error occured 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 blcoked flag.

Returns

A sequence of steps.

Return type

list

Raises

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

Model

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

altwalker.model.validate_model(model_json)

Validate modules, vertices and edges as python identifiers.

Raises

ValidationException – If the model is not a valid model.

altwalker.model.validate_models(models_path)

Validate models from a list of paths.

Parameters

model_paths – 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.

Raises
altwalker.model.get_methods(model_paths, blocked=False)

Return all requrired methods for all models.

Parameters

model_paths – A sequence of path to model files.

Returns

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

altwalker.model.validate_code(executor, methods)

Validate code against a dict of methods.

Raises

ValidationException – If the code is not valid.

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

Verify test code against the model(s).

Parameters
  • path – The path to the project root.

  • package – The name of the package inside the project root.

  • model_paths – A sequence of path to model files.

Raises
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.

Raises

ValidationException – If the model is not a valid model.

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
exception altwalker.exceptions.GraphWalkerError(message)

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

exit_code = 3
exception altwalker.exceptions.AltWalkerError(message)

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

exit_code = 4