State Machine Crawler. Release 8.5

Transcription

1 State Machine Crawler Release 8.5 August 31, 2015

2

3 Contents 1 API Primitives The crawler State collections Error class State graph visualization Command line interface i

4 ii

5 A toolkit for following automata based programming model and facilitate the developer with writing model based tests. The toolkit is called State Machine Crawler instead of plain State Machine because it does not just blindly perform transitions between states but actually finds the shortest path between two states based on the cost of all possible paths between them. The ability to find the shortest path between multiples states comes from a representation of the states in the form of a directed graph. Such model allows to employ pure mathematical algorithms to measure distances between the nodes. For usage examples please have a look at tests.py in the root project directory. Contents 1

6 2 Contents

7 CHAPTER 1 API 1.1 Primitives The primitives of the toolkit are States and Transitions. The first ones are essentially descriptions of certain conditions within the system. The latest - are descriptions of how to change the conditions to perform a semantic move from one state to another. class state_machine_crawler.state(system) A base class for any state of the system States have a _system attribute that represents a SUT. verify() Checks if the system ended up in a desired state. Should raise an exception (e.g. using assert statement) if something is not valid state_machine_crawler.transition(source_state=none, target_state=none, cost=1) A decorator that represents a process of moving from source_state to target_state cost (int) Relative price of the transition. Transitions that take longer time to run are more expensive. The cost has to be experimentally determined. target_state (subclass of State or string self ) The state to which the system should be transitioned, if self is used the transition is done to the holder class itself source_state (subclass of State) The state from which the system should be transitioned The only difference between target_state and source_state is a direction of the relationship. Note: there can be only target_state or only source_state because if a transition from state A to state B is possible it does not at all imply that the opposite transition can be performed the same way. It is also possible to use string values for source_state or target_state in conjunction with StateCollections subclass to define the entry points. Sample usage: class ParentState(State): class YourState(State): 3

8 @transition(source_state=parentstate) def cost=3) def go_to_parent(self): 1.2 The crawler class state_machine_crawler.statemachinecrawler(system, initial_state) The crawler is responsible for orchestrating the transitions of system s states system All transitions shall change the internal state of this object. initial_state The first real state of the system. It must define a transition from the StateMachineCrawler.EntryPoint otherwise the crawler won t be able to find its way through >>> scm = StateMachineCrawler(system_object, InitialState) as_graph(include_entry_point=false) Returns a full graph representation of the state machine as a dict include_entry_point (bool=false) If True, the graph shall include the initial entry point and all related transitions. If False, the initial entry point and all related transitions are excluded from the graph move(state) Performs a transition from the current state to the state passed as an argument state (subclass of State) target state of the system >>> scm.move(stateone) >>> scm.state is StateOne True register_collection(state_collection) Registeres all states in a given state collection state_collection (StateCollection instance) >>> scm.register_collection(state_collection) register_module(module) Registeres all states from a given Python module module (python module) >>> from foobar import module_with_states >>> scm.register_module(module_with_states) register_state(state) Registeres a concrete state and all states related to it inside the state machine state (State subclass) >>> scm.register_state(somestate) state Represents a current state of the sytstem 4 Chapter 1. API

9 verify_all_states(pattern=none, full=false) Makes sure that all states can be visited. It uses a depth first search to find the somewhat the quickest path. pattern (str=none) visits only the states full names of which match the pattern full (bool=false) if True, not only all states are visited but also all transitions are exercised 1.3 State collections class state_machine_crawler.statecollection(name, context_map=none) name (string=none) Collection name. Defaults to module name. context_map (dict) A mapping between state entry points and the actual states. In some cases there is a need to join a bunch of states coming from different modules into a single logical unit. In order to achieve this declare a collection, add a bunch of states to it and register the collection to a state machine: collection = StateCollection("My collection") collection.register_state(stateone) collection.register_state(statetwo) scm.register_collection(collection) Once joined into a collection, states shall be shown as logical cluster in a webview. Apart from entirely decorational use, there is also a practical usecase. States can be declared with entry points for their transitions: class def move(self): collection_one = StateCollection("one", { "initial_state": StateOne }) collection_two = StateCollection("one", { "initial_state": StateTwo }) If the entry points are used as above the framework creates two subclasses of SampleState. One with StateOne as a source for the move transition and one with StateTwo. classmethod from_module(module, name=none, context_map=none) Creates a collection from a module. module (Python module) All State subclasses from this module are added to the collection. name, context_map See constructor 1.3. State collections 5

10 collection = StateCollection(sample_module, "Given name", { "Entry point": SampleStateOne, "Other entry point": SampleStateTwo }) register_collection(collection) Adds a subcollection collection StateCollection subclass register_state(state) Adds a state to a collection state State subclass related_states returns (set) states that do not directly belong to the collection but are referenced from the inside one way or another. states Returns a set of states registred within a collection 1.4 Error class class state_machine_crawler.declarationerror Raised if something is wrong with the state machine declaration in general class state_machine_crawler.transitionerror Raised if the transition or verification fails class state_machine_crawler.unreachablestateerror Raised if state is not reachable 1.5 State graph visualization When state machine gets big it might become difficult to monitor state transitions within it. In such a case a WebView class should be used: class state_machine_crawler.webview(state_machine) state_machine(statemachinecrawler instance) State machine to be monitored Sample usage: >>> app = WebView(state_machine) >>> try: >>> app.start() >>> state_machine.verify_all_states() >>> except TransitionError, e: >>> print e >>> except KeyboardInterrupt: >>> pass >>> app.stop() Once the code is executed, a web service monitoring your state machine shall be started under The url shall be printed to stdout to ease the access. 6 Chapter 1. API

11 An html page of the web service is a dynamic view of the graph that represents the state machine. 1.6 Command line interface In most common case the developer wants to be able to manipulate the SUT without launching python emulator and just use some sort of command line utility. The package provides an autodiscoverable CLI: state_machine_crawler.entry_point() Entry point for state-machine-crawler to manipulate the state machine via a command line. Discovers state machine s instance based on data from state_machine_crawler.json file. JSON config file must have an instance field that should contain a full Python path of a StateMachineCrawler instance. It also may contain a path field that would be either a relative (with respect to parent directory of a the config file) or an absolute file path leading to the directory that contains Python code for the particular state machine. An example of a valid JSON config file: { } "path": "functional_tests", "instance": "functional_tests.instance.state_machine" Sample command line usage: state-machine-crawler -d -w -f Note, it is impossible to use any command line option if the config file is not specified correctly. The CLI as such has the following options: state_machine_crawler.cli(scm) scm(statemachinecrawler instance) State machine to be given a command line interface Available command line arguments: -p, transition_path A path to a file with a chain of states to visit. The states must be delimited by ->. E.g. A -> B -> C -> D -> Z. It may be a standard input itself i.e. directed via a pipe. -t, target-state State to which the system should be transitioned -a, all Exercise all states -s, some Exercise all state names of which match a regexp -f, full Exercise not only all states but also all transitions -w, with-webview Indicates if webview should be started -c, current-state If it is known that the system is in specific state - it is possible to specify it and avoid extra transitions -d, debug Outputs a detailed transition log without-flag Set it to avoid storing the current state of the device in a file text In the end of transition operations stores state machine s info in a text desired location svg In the end of transition operations stores state machine s info as an svg desired location 1.6. Command line interface 7

12 NOTE: -t, -a, -f, -s and -p arguments are mutually exclusive Sample code: scm = StateMachineCrawler(InitialState) scm.register_module(some_module) scm.register_state(somestate) if name == " main ": cli(scm) 8 Chapter 1. API

13 Index A as_graph() (state_machine_crawler.statemachinecrawler method), 4 C cli() (in module state_machine_crawler), 7 D DeclarationError (class in state_machine_crawler), 6 E entry_point() (in module state_machine_crawler), 7 F from_module() (state_machine_crawler.statecollection class method), 5 M move() (state_machine_crawler.statemachinecrawler method), 4 R register_collection() (state_machine_crawler.statecollection method), 6 register_collection() (state_machine_crawler.statemachinecrawler method), 4 register_module() (state_machine_crawler.statemachinecrawler method), 4 register_state() (state_machine_crawler.statecollection method), 6 register_state() (state_machine_crawler.statemachinecrawler method), 4 related_states (state_machine_crawler.statecollection attribute), 6 S State (class in state_machine_crawler), 3 state (state_machine_crawler.statemachinecrawler attribute), 4 StateCollection (class in state_machine_crawler), 5 StateMachineCrawler (class in state_machine_crawler), 4 states (state_machine_crawler.statecollection attribute), 6 T transition() (in module state_machine_crawler), 3 TransitionError (class in state_machine_crawler), 6 U UnreachableStateError (class in state_machine_crawler), 6 V verify() (state_machine_crawler.state method), 3 verify_all_states() (state_machine_crawler.statemachinecrawler method), 4 W WebView (class in state_machine_crawler), 6 9