Changes between Version 16 and Version 17 of TestManagerForTracPluginWorkflow


Ignore:
Timestamp:
Jul 28, 2015, 11:18:10 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • TestManagerForTracPluginWorkflow

    v16 v17  
    1111Every object which has a workflow defined is created in a "new" state, so every transition should consider this as the first state in the state machine.
    1212
    13 
    1413== Example: How to implement Workflow on Test Cases ==
    1514
    … …  
    1716
    1817All is required it to define the desired workflow steps, a.k.a. the "state machine", in the trac.ini file.
    19 A "state machine" is just a definition of the steps (known as states) your artifacts should go through after they are created, of the actions that are allowed in each state and that may transition the artifact into a different state, and of the operations the system should perform on the artifact, or on anything else, along with these actions.
     18A "state machine" is just a definition of the steps (known as states) your artefacts should go through after they are created, of the actions that are allowed in each state and that may transition the artefact into a different state, and of the operations the system should perform on the artefact, or on anything else, along with these actions.
    2019
    2120A state machine indeed defines three things:
    2221 * States - the 'steps' of the workflow. Note that the first step of any workflow will always be "new".
    23  * Transition actions - the User actions avaiable in each state, which may optionally move the artifact from that state to another.
    24  * Operations - what the system must perform on the artifact (but not only) when a certain transition action is triggered.
     22 * Transition actions - the User actions avaiable in each state, which may optionally move the artefact from that state to another.
     23 * Operations - what the system must perform on the artefact (but not only) when a certain transition action is triggered.
    2524
    2625The three elements above are specified in the trac.ini file with the following syntax.
    … …  
    3433For resource type we mean the "realm" string used for resource registration into the Trac environment.
    3534
    36 Resource type names for the Test Manager plugin artifacts are the following:
     35Resource type names for the Test Manager plugin artefacts are the following:
    3736 * testcatalog
    3837 * testcase
    … …  
    4039 * testplan
    4140
    42 For example, to start the definition of a state machine for Test Case, add the following into the trac.ini file:
    43 [testcase-resource_workflow]
    44 
     41For example, to start the definition of a state machine for Test Case, add `[testcase-resource_workflow]` to your `trac.ini` file:
    4542 
    4643=== Definition of transition actions and states: ===
    4744
    48 In the section started with the row above you can define the state machine for the specified artifact.
    49 
    50 To define states of the workflow and actions that allow for moving artifacts from one state to another - so said transition actions, use the following syntax:
     45In the section started with the row above you can define the state machine for the specified artefact.
     46
     47To define states of the workflow and actions that allow for moving artefacts from one state to another - so said transition actions, use the following syntax:
    5148
    5249{{{
    … …  
    5754 * Define a state named '''old state'''
    5855 * Define a state named '''new state'''
    59  * Define a transition action '''action''' that should be available in the state '''old state''' and that, when chosen by the User, will move the artifact into the '''new state'''.
     56 * Define a transition action '''action''' that should be available in the state '''old state''' and that, when chosen by the User, will move the artefact into the '''new state'''.
    6057 
    6158Special cases:
    … …  
    6360 * You can specify that an action should be available in more than one state by separating them with a comma, as in "asleep,calm -> dead".
    6461
    65 
    6662=== Definition of operations to be performed along with specified actions ===
    6763
    68 You can specify that every time an artifact is moved from one state to another by means of a transition action, the system should perfomr one or more operations.
     64You can specify that every time an artefact is moved from one state to another by means of a transition action, the system should perform one or more operations.
    6965
    7066There is a set of [wiki:TestManagerPluginWorkflowOperations out-of-the-box operations] available, but more operations can be provided with your or other plugins by implementing the IWorkflowOperationProvider interface.
    … …  
    8783   '''action'''.permissions = '''permission1''','''permission2''',...
    8884 
    89 [[BR]]
    90 Defining your desired workflow in the trac.ini file '''is all that is required''' to mandate a workflow to the artifacts provided with the [wiki:TestManagerForTracPlugin TestManager] plugin.
    91 
    92 [[BR]]
     85Defining your desired workflow in the trac.ini file '''is all that is required''' to mandate a workflow to the artefacts provided with the [wiki:TestManagerForTracPlugin TestManager] plugin.
     86
    9387=== Example ===
    9488
    … …  
    10599[[BR]]
    106100
    107 {{{
     101{{{#!ini
    108102[testcase-resource_workflow]
    109103sleep = new -> asleep
    … …  
    121115}}}
    122116
    123 [[BR]][[BR]]
    124117== Out-of-the-box operations ==
     118
    125119A set of predefined, [wiki:TestManagerPluginWorkflowOperations out-of-the-box operations] is available, to enrich your workflows not only with state management, but also with side-effects to occur along with state changes.
    126120
    127 [[BR]][[BR]]
    128121== How to provide custom operations ==
    129122
    … …  
    134127To be able to provide custom workflow operations, your Trac Component must implement the IWorkflowOperationProvider interface.
    135128
    136 Let's take a look at a sample operation provider, which is included in the [wiki:TestManagerForTracPlugin TestManager] plugin.
    137 
    138 {{{
     129Let's take a look at a sample operation provider, which is included in the [wiki:TestManagerForTracPlugin TestManager] plugin:
     130
     131{{{#!python
    139132from tracgenericworkflow.api import IWorkflowOperationProvider
    140133
    … …  
    171164}}}
    172165
    173 
    174166As you can see, it's not much code to write. Let's go through it.
    175167
    … …  
    187179   * The name of the operation to be rendered (this in case the provider has stated to provide more than once).
    188180   * The ResourceWorkflowState object representing the current state of the resource in the workflow.
    189    * The Resource object representing the artifact instance being subject to the workflow.
     181   * The Resource object representing the artefact instance being subject to the workflow.
    190182   
    191183   This method must return two results:
    … …  
    199191   * The name of the transition action that is associated with this operation in the trac.ini file.
    200192   * The name of the operation to be performed (this in case the provider has stated to provide more than once).
    201    * The name of the old workflow state from which the artifact is being moved.
    202    * The name of the new workflow state to which the artifact is being moved.
     193   * The name of the old workflow state from which the artefact is being moved.
     194   * The name of the new workflow state to which the artefact is being moved.
    203195   * The ResourceWorkflowState object representing the current state of the resource in the workflow.
    204    * The Resource object representing the artifact instance being subject to the workflow.
     196   * The Resource object representing the artefact instance being subject to the workflow.
    205197 
    206198   There are no requirements as to what the provider must or can do inside this method, except from what's specified next.
    … …  
    208200   It is '''NOT allowed''' to modify the res_wf_state object.
    209201   
    210 This is it. You have added a workflow and your custom operations to the Test Case artifact.
    211 
    212 Of course, you can do the same with the three other artifacts in the [wiki:TestManagerForTracPlugin TestManager] plugin, namely Test Catalogs, Test Plans and Test Cases in Plan (i.e. with a status).
    213 
    214 [[BR]][[BR]]
    215 
    216 == Extend workflow support to any of your artifacts ==
    217 
    218 As said, Test artifacts already have workflow support. To turn it on, all you must do is define the desired workflow in the trac.ini file, as described above.
    219 
    220 But there is more you can do with the TracGenericWorkflow standalone plugin (remember it requires TracGenericClass plugin to be installed, anyway), you can add workflow support to any of your artifacts inside Trac.
     202This is it. You have added a workflow and your custom operations to the Test Case artefact.
     203
     204Of course, you can do the same with the three other artefacts in the [wiki:TestManagerForTracPlugin TestManager] plugin, namely Test Catalogs, Test Plans and Test Cases in Plan (i.e. with a status).
     205
     206== Extend workflow support to any of your artefacts ==
     207
     208As said, Test artefacts already have workflow support. To turn it on, all you must do is define the desired workflow in the trac.ini file, as described above.
     209
     210But there is more you can do with the TracGenericWorkflow standalone plugin (remember it requires TracGenericClass plugin to be installed, anyway), you can add workflow support to any of your artefacts inside Trac.
    221211
    222212To do that, you should do the following steps:
    223213
    224  1. Define your desired workflow - ''explained above''
    225  1. Define any custom operations you may provide on your artifacts - ''explained above''
     214 1. Define your desired workflow - ''explained above''.
     215 1. Define any custom operations you may provide on your artefacts - ''explained above''.
    226216 1. '''Display the workflow markup into your web pages'''. This is what this section is about.
    227217
    228 There are several ways how you can provide markup to web pages in Trac. Here, I'll explain the way I do it in the [wiki:TestManagerForTracPlugin TestManager] plugin, which is by means of the ITemplateStreamFilter.
     218There are several ways how you can provide markup to web pages in Trac. Here, I'll explain the way I do it in the [wiki:TestManagerForTracPlugin TestManager] plugin, which is by means of the '''ITemplateStreamFilter'''.
    229219
    230220To do this, you must:
    231  
    232  1. Implement the ITemplateStreamFilter interface
     221 1. Implement the ITemplateStreamFilter interface.
    233222 1. When you need to display the markup for the workflow support - i.e. the list of available transition actions in the current resource state and the associated operations - call the ResourceWorkflowSystem.get_workflow_markup() method to get the markup, then just add it to your page.
    234223 
    235 You may ask... this is it???
    236 
    237 Yes! You don't have to do anything to:
     224In other words, you don't have to do anything to:
    238225 * Manage you resource states
    239226 * Handle transitions
    240227 * Manage operations
    241228
    242 all this is automatically performed by the plugin.
    243 
    244 So, let's take a look at (a simplified version of) how the [wiki:TestManagerForTracPlugin TestManager] plugin incorporates this web interface support.
    245 
    246 {{{
     229All this is automatically performed by the plugin.
     230
     231So, let's take a look at (a simplified version of) how the [wiki:TestManagerForTracPlugin TestManager] plugin incorporates this web interface support:
     232
     233{{{#!python
    247234from trac.web.api import ITemplateStreamFilter
    248235from tracgenericworkflow.api import ResourceWorkflowSystem
    … …  
    281268 * req: the http request
    282269 * base_href: an href string pointing to the base of your project - e.g. in the context of a wiki page, '..' returns up to your project's base URL.
    283  * realm: the artifact's resource type - e.g. 'testcase' in the examples above.
     270 * realm: the artefact's resource type - e.g. 'testcase' in the examples above.
    284271 * resource: the actual Trac resource instance object of the workflow.
    285272
    286 Note: [wiki:TestManagerForTracPlugin TestManager] artifact resources are made so that their resource ID is a string representation of their key properties, in the form of a JSON dictionary.
    287 This is why you see the following code, where to build a Trac Resource corresponding to a [wiki:TestManagerForTracPlugin TestManager] artifact, I first build the Resource ID as the string representation of the artifact's key properties, then use it to create the Resource:
     273Note: [wiki:TestManagerForTracPlugin TestManager] artefact resources are made so that their resource ID is a string representation of their key properties, in the form of a JSON dictionary.
     274This is why you see the following code, where to build a Trac Resource corresponding to a [wiki:TestManagerForTracPlugin TestManager] artefact, I first build the Resource ID as the string representation of the artefact's key properties, then use it to create the Resource:
    288275
    289276{{{
    … …  
    301288 2. Being notified of state transitions => IWorkflowTransitionListener
    302289
    303 
    304290=== IWorkflowTransitionAuthorization ===
    305291
    306 {{{
     292{{{#!python
    307293class IWorkflowTransitionAuthorization(Interface):
    308294    """
    … …  
    326312=== IWorkflowTransitionListener ===
    327313
    328 {{{
     314{{{#!python
    329315class IWorkflowTransitionListener(Interface):
    330316    """
    … …  
    343329        """
    344330}}}
    345