Creating Automation Keywords

New Automation Keywords

The Robot Framework comes with many Built-In keywords already available. In addition, there are many external libraries (such as
DatabaseLibrary, SSHLibrary, etc…) available. The documentation for each of these libraries can be found on the Robot Framework Standard
Libraries Site in the ‘Standard’ and ‘External’ sections.. Before creating a new keyword, you should become familiar with these standard libraries
as many of these can be used within the custom libraries/keywords that you will create.

Search Existing Automation API

Before creating a new Keyword, you should first check the existing set of libraries to be sure that a similar keyword does not already exist. The
current set of resource files and keywords available can be found here - http://shipoopi/AutomationLibrary/index.php

Determine Who Should Create the New Keyword

The Automation Steering Committee is available to help with the creation of any new keywords related to the Automation Infrastructure. If you
would like to request the committee create the new keyword, please use the following link to submit a request for a new keyword: http://shipoopi/A
utomationLibrary/requestMethod.php You should also follow up with any member of the Automation Committee to provide any additional details
and so they can ask you any questions they have in regards to the new keyword that has been requested. This will also automatically add the
Keyword to the database and be placed in an 'Unassigned' status so that others can search and find this Keyword. This will prevent the
duplication of multiple people creating the same keyword.

If you feel comfortable enough to create the new keyword on your own, continue reading the sections below. While creating the new keyword,
please feel free to refer to any member of the Automation Committee with any questions or to provide direction on how to complete the task in the
most efficient way. Also, if you are creating the Keyword on your own, please first add it to the Automation API on Shipoopi:

Go to the Automation API - http://shipoopi/AutomationLibrary/methodCreate.php

Select the appropriate resource file where the new keyword will reside
Enter in the Keyword name, a brief description and any input or output that is required by this keyword. Enter ‘N/A’ if either of these fields
are not applicable
Set the 'Status' field to 'In Progress'
Set the Owner to your username (i.e. bkobrenski) and set the Needed By Date to your current guess on when the Keyword will be
completed
Click the ‘Add Automation Keyword’ button to submit

Determine the location of the new keyword

It is very important when creating a new keyword that you choose the proper location so that others can easily find and use the keyword. In some
cases this may be an easy decision, but in other cases the keyword may be helpful to other teams. Here is a guideline for determining where to
add your new keyword:

1. If the keyword is not specific to any Seachange Product, it should be included in the 'Automation/lib/Common/Resource '
directory (Examples: grepping a log file or launching a 3rd party tool such as Jmeter)

2. If the keyword is specific to only one product, then it should be included in the ‘Automation/lib/<SeaChange
Product>/Resource’ directory.

Examples:
Automation/lib/Adrenalin6x/Resource
Automation/lib/Adrenalin5x/Resource
Automation/lib/Rave/Resource
Automation/lib/Infusion/Resource

3. If the keyword is common across multiple but not all Products, it should be included in the resource file in the
'Automation/lib/CommonProducts/Resource ' directory (Examples: seachangeService, mmcGUI, cassandraSvc, mmcSvc, etc…)

NOTE: Only the Automation Steering Committee should create new folders under the 'lib' directory in Perforce. If you need a new folder created,
please see any member of the Automation Committee. Any user can add to or modify the keywords included in these files.

Determine the type of module to create

The last decision to make is whether to create the new keyword in a robot resource file or a Python resource file. This decision is entirely up to
the creator of the new keyword. Typically it is much easier and faster to create the new keyword in a robot resource file, making this the
recommended approach. However, there are times when it might not be possible to complete all operations in a simple robot file. In cases like
these, you should use Python to create the new keyword.

Naming Convention
The new keyword should be added to the resource file specific to the functionality being added. For example if you are creating a new keyword
testing the Publisher API, then the new keyword should be added to the resource_publisher.robot file. If the resource file where the new keyword
should go does not yet exist, please follow the following naming convention for creating the new .robot or .py file:

Robot Resource Files: All lowercase with underscore in between words - should start with 'resource'
Example: resource_lab_environment.robot
Python Resource Files: All lowercase with underscore in between words
Example: resource_get_system_info.py
Robot Keywords: Bumpy Case - All lowercase except first letter of word is capitalized, use space between each word
Example: Maximize Browser Window
Python Keywords: All lowercase with underscore in between words
Example: ingest_adi_file

The file name that you choose to store the new keywords should be specific to Component when possible. For example, any Keywords dealing
with the Content Distributor should be stored in a 'resource_cd.robot' file in the lib/Adrenalin6x/Resource directory (as this resource robot file is
specific only to Adrenalin 6.x). Another example would be that any Keywords dealing with Infusion's POIS service should be stored in a
'resource_pois.robot' file in the lib/Infusion/Resource directory.

Components that are shared across multiple components should be stored in the lib/CommonProducts/Resource directory. Examples of these
components and file names are:

Cassandra: resource_cassandra.robot
MMC: resource_mmc.robot
BMS: resource_bms.robot
etc....

NOTE: All files (robot or python) in the Resource directory should ALL be named starting with 'resource_'....

Examples:

Automation
lib
Common
Resource
resource_get_sytem_info.robot
resource_helpers.robot
resource_helpers.py

Helpers Import Files

A Helpers Include file should be created for each SeaChange Product in the respective Automation/Tests directory. For example, the Adrenalin
6.x helpers file (adrenalin6x_helpers_include.robot) has been created in the Automation/Tests/Adrenalin6x directory. The SeaChange Product
specific Helpers file will contain the call to Import each of the required Robot Framework Libraries, External Libraries and Custom Libraries that
are needed for any tests in that SeaChange Product ‘Tests’ directory. This Helpers Include file can then be imported by each robot test script in
order to eliminate the duplication of all these Import statements in each robot test script.

Any time a new resource file is created, the Automation Steering Committee should be notified so they can add the Import of that new file to the
Product Specific Helpers Include File.

Resource File Contents

The contents of the resource file should contain only the following sections:

Settings *
Variables
Keywords

No ‘Test Cases’ should reside in the resource file (see Unit Test below for how the keywords are validated).

Note: * The ‘Settings’ section will typically be empty and not be needed in these resource files as the Imports will usually be done in the Unit Test
and Robot Test Files.
Best Practices
Please adhere to the following when creating the new resource file:

Keyword names should use bumpy case with a space in between words -- Example: Maximum Browser Window
Global Variables should be in all caps with an underscore between each word -- Example: ${DEFAULT_USERNAME}
Local Variables should be in all lowercase with an underscore between each word -- Example: ${login_input_username_locator}
Use at least 4 spaces between columns (use spaces and not tabs)
Comment the Keywords diligently – you should typically not go more than 5-10 lines of code without a comment (#)
Avoid using hard-coded sleeps in code as much as possible. If you need to wait for an operation to complete, use loops with short sleeps
repeated to check for completion rather than using one long sleep command
All keywords must have a documentation or commented section that includes a description, the expected input and the output from the
keyword (if any)

Documentation
Each Keyword created should contain a 'Documentation' section that includes a clear description of the Keyword as well as any Input and Output
to/from the Keyword. The 'Documentation' section should appear at the very top of the Keyword before the 'Arguments' section and before any
calls are made. This documentation is necessary in both Robot and Python Resource Files as it will be used to automatically synchronize the
information that is displayed in the Shipoopi Automation Library API - http://shipoopi/AutomationLibrary/index.php. Be sure to include 1 or more
examples in the documentation as well so that people can easily see how to call that Keyword.

Example of Keyword created in a Robot Resource File:

Stop Service

[Documentation] Stops a service in target machine

... | service_name | Name of target service |

... | status_pattern | String pattern used to verify service status |

... | connection_alias | SSH connection alias |

...

... Input: 0. Service Name

... 1. Status Pattern

... 2. (Optional) Connection Alias – Default: None

...

... Output: None

...

... Example:

... | Stop Service | Publisher | Publisher successfully stopped

[Arguments] ${service_name} ${status_pattern} ${connection_alias}=${None}

Run Keyword If '${connection_alias}' != '${None}' Switch Connection ${connection_alias}

Execute Command /sbin/service ${service_name} stop

..... etc....

Example of Keyword created with a Python Resource File:

def start_service (self, ip_address, service_name)

"""

Restarts the specified service name on the IP provided

This line is also part of the documentation

Input: 0. IP Address

1. Service Name

Output: None
 Example:

| Start Service | ${mmc_ip} | MMC

""""

..... Python code here....

Standard Coding Conventions:

Robot Framework: High level guidelines put together by the Robot community for writing good test cases: https://github.com/robotframework/How
ToWriteGoodTestCases/blob/master/HowToWriteGoodTestCases.rst

Python Custom Libraries: PEP8 Style Guide for python will be used for python based libraries: https://www.python.org/dev/peps/pep-0008/

Completion of New Keyword

Before submitting the new keyword in Perforce, the following set of steps MUST be completed:

Unit Test
Write a unit test for the new keyword. A unit test is stored in a robot script which tests all the keywords in a resource file by passing hard coded
values in keywords. A unit test also covers all possible options including negative scenarios to test any keyword. The name of the unit test should
reflect the name of the resource file. For example if the resource file is called ‘resource_lab_environment.robot’, then the unit test file should be
called ‘lab_environment_unit_test.robot’. This unit test file should consist of 1 or more tests against each keyword that exists in the respective
resource file.

The unit test should be stored in the ‘Automation/lib/<SeaChangeProduct>/Robot’ directory where SeaChangeProduct is the product the keyword
belongs to (i.e. Rave, Adrenalin5x, Adrenalin6x, Infusion, Common, CommonProducts, etc…)

For reference: refer to unit tests under the lib/Common/Robot directory

Example: lab_environment_unit_test.robot

The unit test should contain the following sections: Settings, Variables and Test Cases (no Keywords should be needed). Make sure the unit test
is run and that all previously written tests in that unit test still pass. Consider creating a unit test to validate the new keyword against 1 or more
negative scenarios.

If the unit test you are creating requires any external dependencies, such as databases, remote directories, consider creating a python test script
instead. In these cases, you can take advantage of the Mock module in Python. See the following link for more information on how to use this
module to use mock objects. If using this approach, the location and naming of the unit test file would be the same, except that the extension
would be .py instead of .robot.

Code Review
Perforce has an internal tool called Swarm, which allows modified code to be requested for review. Please follow the ‘Checking In
Changes/Swarm Review Process’ for submitting your new code for review. You should submit all changes in the review, including both the new
keyword and the respective unit test.

Important to Note:

If the keyword is common across multiple products (i.e. Infusion and Adrenalin6x), it should be reviewed by at least 1 member
from your team as well as at least 1 member from the Automation Steering Committee
If the keyword is specific to a single product and will NEVER be used by any other products, then it should be reviewed by at
least 1 member from your team (the Automation Steering Committee does not need to review it)

Automation API
All of the Automated Keywords in the Robot Framework can be found on the Shipoopi Website - http://shipoopi/AutomationLibrary/

This site allows you to manually add new keywords that you are creating as well as request new keywords that you would like to have created for
you. You have the ability to filter the keywords based on name, description, product and a few other fields.

Once the new keyword and unit test have been reviewed and submitted into Perforce, we need to add the information to the Automation API.
This will allow others to easily search for and use this keyword. It is very important that you complete this step as without this, others may end up
duplicating the same keyword.

To add a new resource file (if new resource or .py file was created):

Go to the Automation API - http://shipoopi/AutomationLibrary/moduleCreate.php

Enter in the new module name (same name as file minus the extension)
Change the ‘Type’ to ‘Robot’
Choose the Appropriate Product where the resource file resides (i.e. Infusion, Common, etc…)
Enter a brief description of the new module being added
Click the ‘Add Resource File’ button to submit

To add the new Keyword:

Go to the Automation API - http://shipoopi/AutomationLibrary/methodCreate.php

Select the appropriate resource file where the new keyword will reside
Enter in the Keyword name, a brief description and any input or output that is required by this keyword. Enter ‘N/A’ if either of these fields
are not applicable
Set the 'Status' field to 'Completed' (assuming the keyword is checked in)
Optionally you can add the Owner and the date the Keyword was completed
Click the ‘Add Automation Keyword’ button to submit

Automatic Sync
Any new keywords that have been checked in to any sub-directory of Automation/lib are also automatically synced to this website on Shipoopi. A
scheduled task has been created on 192.168.116.159, which runs every day at 6 AM and 6 PM. This task syncs the latest code from Shipoopi
and then adds any new keywords that were added or updates any keywords that were changed. The information that is synced to the Shipoopi
Automation API Database comes from the 'Documentation' section of the keywords. See the 'Documentation' section above for more information
on the syntax that is required.

The Scheduled Task is called 'Sync Robot Keywords with Shipoopi' and can be modified on 192.168.116.159 (Administrator/itv). The batch file
that runs twice a day is called 'syncKeywords.bat' in the Automation\Tools directory.