API Documentation#

This section of the documentation provides a comprehensive API reference for 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.

Parameters:

  • planner (Planner) – The test planner responsible for determining the next step.

  • executor (Executor) – The test executor responsible for executing steps.

  • reporter (Reporter) – The reporter to record and report test progress.

run()#

Run tests.

Returns:

True if all tests are executed successfully, False otherwise.

Return type:

bool

property status#

The status of the current test run.

Returns:

True if the test run is successful, False otherwise.

Return type:

bool

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.

Parameters:

  • planner (Planner) – The test planner responsible for determining the next step.

  • executor (Executor) – The test executor responsible for executing steps.

  • reporter (Reporter, optional) – The reporter to record and report test progress (default: None).

Returns:

An instance of the Walker class.

Return type:

Walker

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.

    With this method, the test code can directly interact with GraphWalker and modify the model data. A dictionary containing the model data is passed as the first argument to any method or function from the test code by the 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.Planner#

An abstract class that defines the planner protocol.

abstract fail(message)#

Marks the last step as failed.

abstract get_data()#

Get the current data values for the current model.

abstract get_next()#

Return the next step available, if there is one.

abstract get_statistics()#

Return the statistics for the current path.

abstract has_next()#

Return True if there is a next step available.

abstract kill()#

Cleanup resources and kill processes if needed.

abstract load(models)#

Load the models.

abstract restart()#

Resets the current path and the statistics.

abstract set_data(key, value)#

Set data in the current model.

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 verbose 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 verbose flag.

Loader#

class altwalker.loader.ImportlibLoader#
static load(p, root)#

Import and return a module from the given path, which can be a file (a module) or a directory (a package).

This function tries to import a module and if it fails due to a ‘ModuleNotFoundError’, it will try to import the missing module and retry importing the original module.

Parameters:

  • p (str, Path) – The path to the module or package to load.

  • root (str, Path) – Used as an anchor to obtain a unique name for the module being imported so it can safely be stored into sys.modules.

Returns:

The loaded Python module.

Return type:

ModuleType

class altwalker.loader.PrependLoader#
static load(p, root)#

Import and return a module from the given path.

The directory path containing the module will be inserted into the beginning of sys.path if not already there, and then imported with the __import__ builtin.

Parameters:

  • p (str, Path) – The path to the module or package to load.

  • root (str, Path) – Not used.

Returns:

The loaded Python module.

Return type:

ModuleType

class altwalker.loader.AppendLoader#
static load(p, root)#

Import and return a module from the given path.

The directory containing the module is appended to the end of sys.path if not already there, and then imported with the __import__ builtin.

Parameters:

  • p (str, Path) – The path to the module or package to load.

  • root (str, Path) – Not used.

Returns:

The loaded Python module.

Return type:

ModuleType

class altwalker.loader.ImportModes#

Possible values for mode parameter of create_loader.

IMPORTLIB = 'importlib'#
PREPEND = 'prepend'#
APPEND = 'append'#
altwalker.loader.create_loader(mode=None)#

Create a loader for AltWalker.

Parameters:

mode (str) – The importing mode (e.g., ‘importlib’, ‘prepend’, ‘append’).

Raises:

AltWalkerException – If the executor_type is not supported.

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, step=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.

  • step (dict) – The current step.

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', **kwargs)#

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, step=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.

  • step (dict) – The current step.

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, loader=None, import_mode=None, **kwargs)#

Execute methods or functions from a model like object.

execute_step(model_name, name, data=None, step=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.

  • step (dict) – The current step.

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=None, url='http://localhost:5000/', **kwargs)#

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, step=None)#

Execute a step from a model.

has_model(name)#

Check if the module has a class named name.

has_step(model_name, name)#

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

kill()#

Kill the executor service.

load(path)#

Starts the executor service with the given project path, if a service is already running it will kill it before starting the new one.

reset()#

Reset the current execution.

altwalker.executor.create_executor(executor_type, tests_path, **kwargs)#

Create and initialize an executor for AltWalker.

Parameters:

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

  • tests_path (str) – The path to the tests.

  • **kwargs – Additional keyword arguments passed to the executor constructor.

Returns:

An initialized executor instance.

Return type:

Executor

Raises:

AltWalkerException – If the executor_type is not supported.

Reporter#

The reporter plays a crucial role in capturing and presenting the results of a test run. It’s responsible for handling various events during the test execution, and the following methods are called by the Walker class:

  • start(): Called at the beginning of each test run.

  • end(): Called at the end of each test run.

  • step_start(): Invoked before executing each step.

  • step_end(): Invoked after executing each step.

  • report(): This method should return report if the reporter generates one. For example, reporters like PrintReporter or FileReporter might not generate reports but could log data.

It’s important to note that the report() method is not called by the Walker class; its purpose is to provide a report when applicable.

To create a custom reporter, you should implement all of these methods. You can inherit from the Reporter class and override only the methods that you need to customize. This allows you to tailor the reporter’s behavior to your specific requirements while maintaining consistency with the expected interface.

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 information 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 process 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 service.

  • 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(project_path, executor_type, model_paths, executor_url=None, import_mode=None)#

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#

These exceptions are employed in the CLI to manage the exit_code and control the display of GraphWalkerException and AltWalkerException exceptions.

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.