Opereto defines services by a short YAML script called: service specification YAML. Following is an example of a service specification:

          

cmd: python -u run.py

item_properties:
- key: filename
  direction: input
  mandatory: true
  type: text
  value: 
  help: a file name to find
  example: myfile.txt

- key: occurrences
  type: json
  value: 
  direction: output
  example: [
'/tmp/myfile.txt',
'/myfile.txt'
  ]
  help: a list of occurrences of this file (full path)

timeout: 600

type: action 

            

Let us review the specification and see what can you learn about this service:

  1. You know how to run this service: python -u run.py
  2. This service gets a file name string as an input and outputs a JSON list of all occurrences of this file on the host running it
  3. It's an action, meaning that it must run on a remote agent (we'll discuss service types at the end of this article)
  4. It will timeout after 10 minutes

This information is enough for Opereto to execute it on any remote agent, present the relevant user input form in UI, know when to stop if it stops responding for any reason, etc. 

Let us review now each and every specification directive in details:
 

item_properties

item_properties are the service interface. It is an optional list of input or output parameters of the form:       

item_properties:
- key: param1# mandatory
  value: my_value_1# mandatory
  type: text# mandatory
  editor: text# optional
  mandatory: true# optional
  direction: input# optional
  help: an example of a text input# optional
  example: my text input# optional
  store:# optional

                       

ElementMandatoryDescription
keyyesthe name of the input/output property
valueyes
the default value of the property. The default is null.
typeno
valid types are: text, integer, json, boolean, list (comma delimited strings) and environment (a particular built-in property type to pass Opereto environments to services).
The default is text.
editornospecifies the web UI editor for this property. If not specified Opereto will select a default editor based on the type (e.g. a textfield for a text value, a checkbox for a boolean, etc.).
Editor types are:
  • text
  • number
  • json
  • textarea
  • checkbox
  • selectbox
  • multiselectbox
  • itemselector
mandatoryno
specifying if this property must have a value specified. The default is false.
directionno
specifies if this property is an ‘input,' ‘output’ or ‘both' which means the service code may override this property's value during execution. Opereto passes only properties with 'input' direction specification to the executable service code upon initiation. Also, the output of data will only be allowed for output properties. The default is input.
storeno
a map of keys and values to select from for a given property. Following are the main usages of store:


1. environment type (see Opereto Environments):     

item_properties:
- key: sut_environment
  type: environment
  direction: input
  value:
  store:
    environment_types: simple_test_topology, complex_test_topology 

      

2. multi selector editor       

item_properties:
-  key: clients
   editor: multiselector
   type: list
   mandatory: false
   store:
   client1: client1
        client2: client2
        client3: client3
 
         

3. item selector editor     

item_properties:
-  key: clients
   editor: itemselector
   type: list
   mandatory: false
   store:
   client1: client1
        client2: client2
        client3: client3
       
exampleno
If specified, Opereto adds it to the service info page.
helpno
A short text description of the property. Opereto adds this text to the documentation generated by Opereto for the given service.

cmd

Specifies the command line to run the service executable.

In case that the service executable command requires input parameters, Opereto enables to map properties to command line parameters as demonstrated in the following example:

    

cmd: python -u myapp.py ${param1} ${param2}            
item_properties:
- key: param1
  type: text
  value: my_value_1
  editor: text
  mandatory: true
  direction: input
- key: param2
  type: text
  value: my_value_2
  editor: text
  mandatory: true
  direction: input
...
...

     

In any event, item properties are passed to the service executable in several ways and may be processed by the service code. For more details about service input mechanism see the Handling Service Input / Output article.


bell-2x.png In most languages, when running code from command line, all STDOUT, and STDERR content will be redirected to shell immediately without buffering. However, in some cases, a particular flag or config parameter should be added to the command. In Python, for example, adding the flag “-u” to the command instruct Python interpreter to redirect all console output to the shell without buffering it: python -u myapp.py.


cmd of type "shell"

In case of a shell command type, it is also possible to add additional definitions, enabling to define a single service for different OS.


cmd:
  type: shell
  command:
    default: bash run.sh
    windows: cmd /c run.bat
    linux: bash run.sh
timeout: 600
type: action


The windows and linux specifications are optional. If the Os are one of these then the command defined in them they will be executed. 


Valid exit codes

It is possible to define a list of valid exit codes for the command. In case the command returns none of the defined valid_exit_codes, the command will fail.

The definition of the valid_exit_codes is as array:


cmd:
  type: shell
  command:
    default: bash run.sh
  valid_exit_codes: [0,10,3]
timeout: 600
type: action



timeout

The default service execution timeout (in seconds). The user can override this timeout upon service invocation.


type

Service types are classifiers that direct Opereto how to operate a given service and what constraints to put on the service specification YAML. 

In general, there are three major types: action, cycle, and container.


action

An action is the most common service type. It requires a specification of a service repository, cmd, and timeout. Other service specification directives are optional.

Opereto also provides a few action subtypes to support services that operate on environments, in particular for the purpose of managing a complex system automated testing on multi-tier test environments.  In addition to the mandatory default directive that services of type 'action' require, these subtypes also expect additional input or output properties to be specified. 


The following table provides the full list of the 'action' family service types.

 

Service TypeIconDescriptionAdditional Constraints
action
A generic type for all services The default type.
setup
Setup of a test environment or toolsRequires also an output property of type 'environment' and key 'sut_environment'
teardownTeardown of a test environment or toolsRequires also an input property of type 'environment' and key 'sut_environment'
fixture
Configure a test environment to particular stateRequires also an input property of type 'environment' and key 'sut_environment'
analyzerAnalyze the condition of a given test environment Requires also an input property of type 'environment' and key 'sut_environment'
fetcherFetch data from a given test environment Requires also an input property of type 'environment' and key 'sut_environment'
testRun test flow on a given test environmentRequires also an input property of type 'environment' and key 'sut_environment'


All services of the action type family run on agents and thus, the service executor need to provide a name of an Agent or agents to use. So far, we only discussed services that run on remote agents. Opereto supports two service types are special built-in services that require no agent to run on. Instead, they are processed by Opereto's state machine on the cluster.


cycle 


A cycle is a built-in mechanism in Opereto aimed for building and managing a complete test cycle stack. Cycles have different service specification YAML scheme than described above.

To learn more about it, please refer to the Cycle Management article


container

A container is a built-in mechanism in Opereto to pack few services within a single service. To learn more about containers and their specification YAML, please refer to the Service Containers article. 



repository (optional)

A specification of the service codes source location. It is an optional field. Opereto keeps this information in case that you want to re-fetch the service code from this repo at any later stage. 

Opereto supports four types of repositories:


1. GIT - a directory in a git repository     

repository:
repo_type: git
url: git@bitbucket.org:my_account_name/my_project.git
branch: master
ot_dir: mydir      ## leave empty if root directory

      

2. SVN - a directory in a git repository     

repository:
repo_type: svn
url: svn://myhost/myrepo
username:                      ## optional
password                       ## optional
ot_dir: my_service_dir   ## leave empty if root directory

     

3. HTTP - a zip file stored in any HTTP(S) based storage (dropbox, google drive..)    

repository:
repo_type: http
url: https://www.dropbox.com/s/1234567890/MyFile.zip?dl=0
username:                      ## optional
username                       ## optional
ot_dir: my_service_dir    ## leave empty if root directory

    

4. AWS S3 - a zip file stored in Amazon web services S3      

repository:
repo_type: s3
bucket: my_bucket/my_service.zip
access_key: MY_ACCESS_KEY
secret_key: MY_SECRET_KEY                    
ot_dir: my_service_dir   ## leave empty if root directory

      


Service Verification

Opereto provides a verification mechanism to check if a service specification YAML is valid. 
cmd:
  type: shell
  command:
    default: bash run.sh
    windows: cmd /c run.bat
    linux: bash run.sh
timeout: 600
type: action