Note
This document is under active development!

If you find errors or missing information in this document, please don’t hesitate to submit an issue or open a pull request with a fix. We encourage you to submit questions and discuss any aspects of the project on github.

We are happy to welcome new contributors!

Introduction to Cerberus

In this section, you will find information on Cerberus.

FR Something is incorrect/missing in this section? Feel free to submit modification.

1. What is Cerberus?

Cerberus is a webapplication, open source, test repository, user friendly, can interface with robot in multiple technologies.

FR Something is incorrect/missing in this section? Feel free to submit modification.


Getting started

In this section, you will find information on how is organized the Cerberus application.

We assume that you already configured your application, as described in the Application configuration section.

FR Something is incorrect/missing in this section? Feel free to submit modification.

2. Welcome to Cerberus application

2.1. Login

Opening Cerberus, you will be invited to login with the information you should have received from your Cerberus administrator.

LoginPage

Note
If you did not receive any credential, please contact your Cerberus administrator.
Note
If you forgot your password, you can retrieve it following the forgot password wizard.

Once you’re logged in, you will access to the homepage.

2.2. Homepage

The homepage is showing information on
  • testcases set by application grouped by status (See the [workflow] section for more information);

  • testcase executions by tag (the last ones by default, or customizable as described in the Customization section);

  • the application versions deployed on environment;

Homepage

2.2.1. Customization

HomepageCustomTag

FR Something is incorrect/missing in this section? Feel free to submit modification.

3. Overview

In this section, you will find general information on Cerberus. How it is organized, How the tables are Customizable…​etc.

FR Something is incorrect/missing in this section? Feel free to submit modification.


Test Management

In this section, you will find information on test management in Cerberus.

FR Something is incorrect/missing in this section? Feel free to submit modification.

4. Test

In this section, you will find information on Test in Cerberus.

Test description…​

TestPage

4.1. Test attributes

Field

Description

Test

Test name.

Description

Description of the test.

Active

Define if the test is active.

Automated

Define if the test contains automated testcase.

4.2. Create test

  1. Go to Test → Test. CreateTest

  2. Click on Create Test.

    1. Feed the Test field with the test name.

    2. Feed the Description field with a short description of this test.

    3. Select the activation information in the Active field.

    4. Select the automation information in the Automated field.

    5. Click on Save.

FR Something is incorrect/missing in this section? Feel free to submit modification.

5. TestCase

In this section, you will find information on TestCase in Cerberus.

5.1. TestCase List

TestCaseListPage

5.2. Shortcut

5.2.1. Edit TestCase

TestCaseEdit

5.2.2. Delete TestCase

TestCaseDelete

5.2.3. Run TestCase

TestCaseRun

5.2.4. Duplicate TestCase

TestCaseDuplicate

5.3. TestCase attributes

Field

Description

Test

Test name on which testcase is linked.

Testcase

An ID.

Description

Define if the test is active.

Application

The application for which the testcase is defined.

5.4. Create TestCase

  1. Go to TestCase → TestCase List. CreateTestCase

  2. Click on Create TestCase.

    1. Feed the Test field with the test name.

    2. Feed the Description field with a short description of this test.

    3. Continue to describe.

    4. Click on Save.

5.5. Implement TestCase

5.5.1. Step

  1. Click on Add step to display the following window. TestCasePage

  2. Feed a Description and click on Add for a new step.

  3. Or search for a step in library then click on Add.

testcaseaddstep

Your step is created. if you want to put it in library, just click on the book on the right side. A step in library will be available to add it in all test cases of your current system.

testcasesteplibrary

In the following screenshot you can see a use step. This step is imported from the previous library step. You are not able to modify it (all fields are grey). But you can find a link at the top to open the library if you want to modify your step. All use steps from this library will be impacted by your modification.

To modify only this use step, you have to click on the padlock icon but it will not be a use step anymore. (modification on library step will not affect it)

testcaseusestep

Note
You have the possibility to switch the position of your steps by clicking on the 3 dots.

testcaseusestep testcaseusestep

5.5.2. Action

Action

Description

Example

Unknown

Unknown action. Default Action when creating a new action

keypress

will allow you to press any key in the current web page. Value1 : Keycode of the key to press Example : ENTER

hidekeyboard

Hide the currently visible keyboard

swipe

TBD

click

will allow you to click on an element inside the current page. Value1 Identifier and name of the element to click in the form of : identifier=html_reference. Example : id=html_reference

mouseButtonLeftPress

TBD

mouseButtonLeftRelease

TBD

doubleClick

will allow you to double click on an element inside the current page. Value1 Identifier and name of the element to click in the form of : identifier=html_reference. Example : id=html_reference

rightClick

will allow you to right click on an element inside the current page. Value1 Identifier and name of the element to click in the form of : identifier=html_reference. Example : id=html_reference

focustoIframe

TBD

focustoDefaultIframe

TBD

Switchtowindow

TBD

manageDialog

TBD

mouseOver

Mouse cursor over an object Element path : the id of the element

OpenUrlWithBase

TBD

OpenUrlLogin

TBD

OpenUrl

TBD

select

TBD

type

Write a data in a field. Element path : the id of the field Property Name : the property containing the value to type (can be a property or text.

wait

Wait for a certain amount of time Feed a number (ms) or wait for element present feed an element (xpath)

CallSoapWithBase

TBD

CallSoap

To call a SOAP. Feed one the following field Soap Name (library) : Name of the SOAP stored in library Property Name : Name of the property if the SOAP is defined in property

removeDifference

TBD

executeSqlUpdate

will allow you to execute SQL update (insert,delete,update). Feed the Database Name and the Script to execute. Database has to be declared to your system and environment.

executeSqlStoredProcedure

will allow you to execute SQL stored procedure. Feed the Database Name and the Stored Procedure to execute. Database has to be declared to your system and environment.

CalculateProperty

will allow you to calculate a Property defined in the property section of the test case. [Optional] Feed Value2 with another property to affect to the previous Property Name a new value. Useful to override the one defined from the property section during an execution.

doNothing

Just perform no action. No action will be executed and engine will go to the next action or control

skipAction

Skip this action. No action will be executed and engine will go to the next action. Controls associated to this action will be skipped too.

5.5.3. Control

Control

Description

Example

Unknown

Default control when creating a new control

getPageSource

TBD

skipControl

Skip the control.

takeScreenshot

Take a screenshot

verifyElementClickable

OK if Element is clickable.

verifyElementDifferent

TBD

verifyElementinElement

TBD

verifyElementEquals

TBD

verifyElementNotClickable

TBD

verifyElementNotPresent

TBD

verifyElementNotVisible

TBD

verifyElementPresent

OK if Element is found on the current page.

verifyElementVisible

OK if Element is visible on the current page.

verifyElementDifferent

TBD

verifyIntegerEquals

OK if the Integer1 is equal to the Integer2.

verifyIntegerGreater

OK if the Integer1 is greater than the Integer2.

verifyIntegerMinor

OK if the Integer1 is lower than the Integer2.

verifyRegexInElement

TBD

verifyStringContains

OK if Property String1 contains the String2.

verifyStringEqual

OK if the String1 is equal to the String2.

verifyStringGreater

OK if the String1 is greater than to the String2 (After in a dictonnary)

String1 : ZZZ String2 : AAA

verifyStringMinor

OK if the String1 is minor than to the String2 (before in a dictonnary)

String1 : AAA String2 : ZZZ

verifyTextInDialog

TBD

verifyTextInElement

OK if the text found in Element is equal to the Text indicated

Element : //StatusCode Text : OK

verifyTextInPage

TBD

verifyTextNotInElement

OK if the text found in Element is not equal to the Text indicated

Element : //StatusCode Text : KO

verifyTextNotInPage

TBD

verifyTitle

TBD

verifyUrl

OK if the URL of the current page equal to the URL indicated .

verifyXmlTreeStructure

TBD

5.5.4. Property

When Clicking on Button buttonManageProperties, the Window "Manage Properties" will open. From there you can :

  • either manage your TestCase properties

  • or see your inherited properties - coming from the step libraries of your use steps.

windowManageProperties

Field

Description

Property

Name of the property.

Type

The way the property is going to be calculated.

Value

Value of the property.

DB

DataBase in which the property will "executeSql".

Length

When calculating a list of values, defines the number of rows the property will return.

Row Limit

When returning a list of values, limits the number of rows the property will consider for random purposes.

Nature

Defines the unique value that will be used in the execution. By default, STATIC has no rules defined : it will take the first result it finds.

Desription

Description of the property.

Countries

Countries for which the property will be calculated (environment parameter).

5.5.5. Variables

You can use variables in the action and control’s values. These variable are define in cerberus and you can have access to them with the right syntax.

A variable is defined between %

The easiest way to feed an action with a property or an object, is to use the auto-completion :

  1. Create your property or your application object in advance

  2. Type "%"

  3. Select property or object

  4. Select property-name or object-name

  5. If it’s an object, select its value / picture path / picture url

testCaseVariables

These syntax are available:

  1. %property.myproperty% : Get the property myproperty

  2. %object.myobject.value% : Get the application object myobject’s value

  3. %object.myobject.picturepath% : Get the application object myobject’s picture path

  4. %object.myobject.pictureurl% : Get the application object myobject’s picure url

Below you will find usefull properties :

Value

Description

%SYS_SYSTEM%

System value

%SYS_APPLI%

Application reference

%SYS_APP_DOMAIN%

Domain of the Application

%SYS_APP_VAR1%

VAR1 of the application on the environment.

%SYS_APP_VAR2%

VAR2 of the application on the environment.

%SYS_APP_VAR3%

VAR3 of the application on the environment.

%SYS_APP_VAR4%

VAR4 of the application on the environment.

%SYS_ENV%

Environment value

%SYS_ENVGP%

Environment group code

%SYS_COUNTRY%

Country code

%SYS_TEST%

Test.

%SYS_TESTCASE%

TestCase

%SYS_COUNTRYGP1%

Country group1 value

%SYS_SSIP%

Selenium server IP

%SYS_SSPORT%

Selenium server port

%SYS_BROWSER%

Browser name of the current execution.

%SYS_TAG%

Execution tag

%SYS_EXECUTIONID%

Execution ID

%SYS_EXESTART%

Start date and time of the execution with format : 2016-12-31 21:24:53.008.

%SYS_EXESTORAGEURL%

Path where media are stored (based from the exeid).

%SYS_STEP.n.RETURNCODE%

Return Code of the step n. n being the execution sequence of the step (sort).

%SYS_TODAY-yyyy%

Year of today

%SYS_TODAY-MM%

Month of today

%SYS_TODAY-dd%

Day of today

%SYS_TODAY-doy%

Day of today from the beginning of the year

%SYS_TODAY-HH%

Hour of today

%SYS_TODAY-mm%

Minute of today

%SYS_TODAY-ss%

Second of today

%SYS_YESTERDAY-yyyy%

Year of yesterday

%SYS_YESTERDAY-MM%

Month of yesterday

%SYS_YESTERDAY-dd%

Day of yesterday

%SYS_TODAY-doy%

Day of yesterday from the beginning of the year

%SYS_YESTERDAY-HH%

Hour of yesterday

%SYS_YESTERDAY-mm%

Minute of yesterday

%SYS_YESTERDAY-ss%

Second of yesterday

%SYS_ELAPSED-EXESTART%

Number of milisecond since the start of the execution.

%SYS_ELAPSED-STEPSTART%

Number of milisecond since the start of the execution of the current step.

You will find below some tricks which help you to implement specific test cases.

Note
It is possible to create a random property with a number of digit defined. You have to feed the property fields like the screenshot below. This property will be different for each execution. Example: 884592, 004795 TestCaseRandomProperty

FR Something is incorrect/missing in this section? Feel free to submit modification.

6. TestCase execution

In this section, you will find information on test execution in Cerberus.

RunTestSelection

RunRobotSettings

RunExecutionSettings

FR Something is incorrect/missing in this section? Feel free to submit modification.

7. Campaign management

In this section, you will find information on test campaign management in Cerberus.

7.1. Test battery

A battery is a list of testcase.

7.2. Test campaign

A campaign is a list of test battery for one(several) country(ies) on one(several) environment(s).

FR Something is incorrect/missing in this section? Feel free to submit modification.

8. Label

In this section, you will find the bla bla

Logo

8.1. Label attributes

Field

Description

System

System on which the label will be available.

Label

Name of the label.

Color

Color in #hex format.

Parent Label ID

Not implemented yet! Allow to link the label to another one in order to group them.

Description

This is a short description of the label.

8.2. Create label

  1. Go to TestCase → Label. CreateLabel

  2. Click on Create Label button.

    1. Select the System on which the label will be available.

    2. Feed the Label field with the name of the label.

    3. Choose the Color to apply to this label.

    4. Feed the Description field with a short description of the label.

    5. Click on Save.

FR Something is incorrect/missing in this section? Feel free to submit modification.


Library

In this section, you will find information on library in Cerberus

FR Something is incorrect/missing in this section? Feel free to submit modification.

9. Data library

In this section, you will find information on data library in Cerberus.

9.1. Create data

  1. Go to Data → Data Library. testdatapage

  2. Click on Create New Entry button.

    1. Feed the Name field

    2. Select the Type of the data.

    3. Select a System, an Environment, a Country (not mandatory fields).

    4. Feed the fields of your configurations.

    5. Feed the Description field with a short description of the data.

    6. Go to SubData tab

    7. Feed subdata information depending of your configuration. Refer to Data configurations for more information

    8. Click on Add.

The first sub-data does not require a name, %my_data% will return sub-data 1 and %my_data(sub-data2)% will return value of the sub-data2.

If you do not select an Environment, a system and a country, your data will be available for all environments,systems and countries.

9.2. Data configurations

9.2.1. Internal configuration

No specific configuration needed, just feed a static value in subdata tab.

testdatacreatenewsubdata

9.2.2. SOAP configuration

Field

Description

Database

Database where the Service Path will be requested. (not mandatory)

Service Path

Location of the service. Example: http://mydomain/mywebservicelocationmywebservicelocation

Method

Method that is invoked by the SOAP request/call.

Envelope

Envelope that is sent in the SOAP request.

9.2.3. SQL configuration

Field

Description

Database

Database where the script attribute should be executed .

Script

Script you want to execute.

9.2.4. CSV configuration

Field

Description

Database

TBD

CSV URL

CSV URL specifies the URL where the CSV can be reached.

Separator

Separator used parsing a CSV.

FR Something is incorrect/missing in this section? Feel free to submit modification.

10. SOAP Library

In this section, you will find information on SOAP library in Cerberus.

FR Something is incorrect/missing in this section? Feel free to submit modification.

11. SQL Library

In this section, you will find information on SQL library in Cerberus.

FR Something is incorrect/missing in this section? Feel free to submit modification.


Integration

In this section, you will find information on how to use Cerberus in your continuous integration organization.

FR Something is incorrect/missing in this section? Feel free to submit modification.

12. Environment

In this section, you will find information on how to manage environment in Cerberus.

EnvironmentPage

12.1. Create environment

  1. Go to Integration → Environment CreateEnvironment

  2. Click on Create New Environment

    1. Select the System on which the environment will be created.

    2. Select the Country of the environment. See Country section for more information.

    3. Select the Environement. See Environment section for more information.

    4. Continue to describe…​

    5. Click on Save

FR Something is incorrect/missing in this section? Feel free to submit modification.

13. Application configuration

In this section, you will find information on application configuration in Cerberus.

ApplicationPage

13.1. Application attributes

Field

Description

Application

Cell in column 2, row 3

Description

Cell in column 2, row 3

Sort

Cell in column 2, row 3

Type

The Type of the application define whether the application is a GUI, a service or a batch treatment. More detail in the Application type section.

New Bug URL

This correspond to the URL that points to the page where a new bug can be created on the Bug system of the application. More detail in the New Bug URL section.

13.1.1. Application type

Application type recognizable by Cerberus
  • APK (Android application)

  • BAT (BATCH application)

  • GUI (Web application)

  • IPA (IOS application)

  • SRV (Service)

  • WS (Web Service)

  • NONE (Not defined)

13.1.2. New Bug URL

This correspond to the URL that points to the page where a new bug can be created on the Bug system of the application.

The following variables can be used inside the URL :

%TEST%

Test

%TESTCASE%

Test case reference

%TESTCASEDESC%

Description of the test case

%EXEID%

Execution ID

%EXEDATE%

Start date and time of the execution

%ENV%

Environment

%COUNTRY%

Country

%BUILD%

Build

%REV%

Revision

13.2. Create application

  1. Go to Integration → Application CreateApplication

  2. Click on Create New Application

    1. Feed the Application field with the application name.

    2. Feed the Description field with a short description of this application.

    3. Choose the application type in Type

    4. Select the application deploy type in Deploy Type

    5. Click on Save

FR Something is incorrect/missing in this section? Feel free to submit modification.

14. Application Object

In this section, you will find information on application object in Cerberus.

ApplicationPage

14.1. Application object attributes

Field

Description

Application

The application linked to the object

Object

The name of the object

Value

The value of the object

File Name

The preview of the picture of the object

FR Something is incorrect/missing in this section? Feel free to submit modification.

15. Deploy type

In this section, you will find information on deploy type.

Logo

15.1. Deploy Type attributes

Field

Description

Deploy Type

A name of a deploy type.

Description

A description of the deploy type.

15.2. Create deploy type

  1. Go to Integration → DeployType CreateDeployType

  2. Click on Create New Deployment Type.

    1. Feed the Deploy Type field with a name.

    2. Feed the Description field with a short description of this deploy type.

    3. Click on Save.

FR Something is incorrect/missing in this section? Feel free to submit modification.

16. Batch

In this section, you will find information on batch

BatchPage

16.1. Batch invariant attributes

Field

Description

Batch

The name of the batch.

System

The system for which the batch will be available.

Description

A description of the batch.

16.2. Create deploy type

  1. Go to Integration → Batch. CreateBatch

  2. Click on Create New Batch.

    1. Feed the Deploy Type field with a name.

    2. Select the system for which the batch will be available.

    3. Feed the Description field with a short description of this batch.

    4. Click on Save.

FR Something is incorrect/missing in this section? Feel free to submit modification.

17. Project

In this section, you will find information on project in Cerberus

ProjectPage

17.1. Project attributes

Field

Description

Project

The name of the project.

Code

A code number for the project.

Description

A description of the project.

Active

Define if the project is active or not.

17.2. Create deploy type

  1. Go to Integration → Project. CreateBatch

  2. Click on Create new Project.

    1. Feed the Project field with a name.

    2. Feed the Code field of the project.

    3. Feed the Description field with a short description of this project.

    4. Click on Save.

FR Something is incorrect/missing in this section? Feel free to submit modification.

18. Build content

In this section, you will find information on build content in Cerberus

BuildContentPage

18.1. Build content attributes

Field

Description

To build

To Build.

18.2. Create build content

18.2.1. Manually

  1. Go to Integration → Build Content. CreateBatch

  2. Click on Create new build content.

    1. Select the Build.

    2. Continue to describe.

    3. Click on Save.

18.2.2. Automatically

To describe.

FR Something is incorrect/missing in this section? Feel free to submit modification.

19. Build / Revision

In this section, you will find information on build revision invariants

BuildRevisionPage

19.1. Build Revision invariant attributes

Field

Description

System

The system for which the batch will be available.

Level

to describe.

Sequence

to describe.

Version Name

to describe.

19.2. Create build/revision invariant

  1. Go to Integration → Build Rev Definition. CreateBatch

  2. Click on Create new build revision definition.

    1. Select the system for which the build/revision will be available.

    2. Select the Level. 1 for Build and 2 for Revision.

    3. Feed the Sequence field with a number to sort the build/revision.

    4. Feed the Version Name field that will be displayed.

    5. Click on Save.

FR Something is incorrect/missing in this section? Feel free to submit modification.


Administration

In this section, you will find information on all page and services enabled for administrators.

FR Something is incorrect/missing in this section? Feel free to submit modification.

20. User management

In this section, you will find information about Cerberus user management.

20.1. User creation

20.2. User rights

20.3. Access by system

FR Something is incorrect/missing in this section? Feel free to submit modification.

21. Log viewer

Most of the change triggered in Cerberus are recorded in a table.

logviewer

Warning
To guaranty performance of Cerbeurs over the time, please refer to Clean Database section to get information on database maintenance operation.

FR Something is incorrect/missing in this section? Feel free to submit modification.

22. Database maintenance

Note
Every new release of Cerberus come with embeded scripts to upgrade the database in order to guaranty consistency between the application and its database.

After updating your cerberus version, as described in the Upgrade Cerberus Version section, you will be notified logging in Cerberus as an administrator.

databasemaintenance

Then, you are redirected to the Cerberus Database Maintenance page that allow to apply the scripts one by one.

databasemaintenance

When the database is up-to-date, you will find this information.

databasemaintenance

Warning
Application and Database Must be in the same version.

FR Something is incorrect/missing in this section? Feel free to submit modification.

23. Parameters

In this section, you will find information about Cerberus parameters.

Warning
The tunning of the parameters is necessary to unlock all the features, as described in the Cerberus configuration section.

Logo

23.1. Parameter attributes

Field

Description

Parameter

The parameter recognized by Cerberus.

Value

The default value used in case the system value is empty.

System Value

The specific value for the system.

Description

A description on the parameter.

FR Something is incorrect/missing in this section? Feel free to submit modification.

24. Invariants

In this section, you will find information on invariant private and public.

Note
Private invariants are not editable because used by the Cerberus engine or the user interface.

Logo

24.1. Invariant attributes

Field

Description

IdName

The name of the invariant.

Value

The value set for the invariant.

Sort

An integer used to sort invariants.

Description

The description of the invariant.

Very Short Desc

A very short desc that can be displayed in the invariant.

Group1

A first level of aggregation to group invariant.

Group2

A second level of aggregation to group invariant.

Group3

A third level of aggregation to group invariant.

24.2. Create public invariant

  1. Go to Administration → Invariant. CreateInvariant

  2. Click on Create Invariant.

    1. Select the invariant type in IdName field.

    2. Feed the Value field with the value of the invariant.

    3. Feed the Sort field with an integer which will define the order the invariant will be sorted by Cerberus.

    4. Feed the Description field with a description of this invariant.

    5. Feed the Very Short Desc field with a short description of this invariant.

    6. Feed the Group1 (Optional) field with a name to aggregate invariant.

    7. Feed the Group2 (Optional) field with a name to aggregate invariant.

    8. Feed the Group3 (Optional) field with a name to aggregate invariant.

    9. Click on Save.

24.3. Invariant List

24.3.1. Country

24.3.2. Environment

24.3.3. System

FR Something is incorrect/missing in this section? Feel free to submit modification.

25. Cerberus Monitoring

In this section, you will find information on cerberus monitoring page.

cerberusmonitoring1

cerberusmonitoring2

FR Something is incorrect/missing in this section? Feel free to submit modification.


Installation

This section describes how to install Cerberus and its associated external tools.

FR Something is incorrect/missing in this section? Feel free to submit modification.

26. Cerberus installation

26.1. Technical architecture

Logo

FR Something is incorrect/missing in this section? Feel free to submit modification.

26.2. Installation guide

26.3. Manual installation

26.4. Docker

  1. For Windows :

    1. Install Git for Windows -→ https://git-for-windows.github.io/

    2. Install Docker for Windows -→ https://docs.docker.com/docker-for-windows/

    3. Install Docker Toolbox for Windows -→ https://docs.docker.com/toolbox/toolbox_install_windows/

    4. Clone Cerberus-docker to the desired location :

      1. Go to the desired location folder

      2. Right click into the folder, and click Git Bash Here gitBashHere

      3. Type the following command into Git Cmd Prompt : "git clone https://github.com/cerberustesting/cerberus-docker.git" gitBashPrompt

      4. Wait for cerberus-docker to clone…​

    5. Run Docker. /!\ You may have to go into Docker settings to "share the drive" on which you put cerberus

    6. Run Windows Command Prompt as administrator, navigate to your desired location, then subfolders compositions/cerberus-glassfish-mysql winCmdPrompt

    7. Execute the following command :

      1. either "docker-compose up" to run the docker-compose normally

      2. or "docker-compose up -d" to run the docker-compose asynchronously

      3. or "docker-compose up -d --remove-orphans" to run the docker-compose and remove already existing images

      4. or "docker-compose scale selenium-node-firefox=3 selenium-node-chrome=3" to add more nodes to your Selenium Grid

    8. Wait for the images to startup

    9. Open your favorite browser and go to <docker_host>:18080/Cerberus, where <docker_host> is your Docker host

  1. For Mac :

  2. For Linux :

FR Something is incorrect/missing in this section? Feel free to submit modification.

26.5. Cerberus database init

Database init instruction

FR Something is incorrect/missing in this section? Feel free to submit modification.

26.6. Cerberus configuration

Installation introduction

FR Something is incorrect/missing in this section? Feel free to submit modification.

27. External tools

For each application type there is a specific engine to run tests under it. For instance, Web applications will be handled by the Selenium Web browser automation tool.

The main goal of Cerberus is to gather this tool ecosystem to provide a common way to describe and run tests, whatever the kind of application type.

Hereafter the list of compatible application types and their associated external tool:

Table 1. Application type and associated external tools
Application types Associated external tool

Web

Selenium

Mobile (Android, Iphone)

Appium

Heavy

Sikuli

Web services

Cerberus internal implementation

The following sections will cover installation and configuration procedures for each associated external tool, and interface description with cloud-based cross-browser testing tools.

27.1. Selenium

Unresolved directive in documentation_en.adoc - include::include/en/installation_externaltools_selenium_en.adoc[]

27.2. Appium

Appium is an open source test automation framework for use with native, hybrid and mobile Web applications. It drives iOS, Android, and Windows applications using the WebDriver protocol.

This procedure covers installation and configuration of Appium v.1.6.2+.

27.2.2. Appium server installation

Android

Install Android SDK v.1.7+. See official documentation here and here for more details.

IOS
Installation
  1. Install Xcode 8.1+

  2. Install the Apple Developer Tools via this external documentation

  3. Follow the complete procedure from this external documentation and apply the following commands and fixes:

    1. Carthage cannot be installed via npm but brew. Thus, install Carthage by executing:

      brew install carthage
    2. Execute the following additional commands:

      npm install -g ios-deploy --unsafe-perm=true
      npm install -g deviceconsole
      brew uninstall ideviceinstaller
      brew uninstall libimobiledevice
      brew install --HEAD libimobiledevice
      brew unlink libimobiledevice && brew link libimobiledevice
      brew install ideviceinstaller
      brew unlink ideviceinstaller && brew link ideviceinstaller
      Caution
      Note about the current Appium version from npm

      At the time of writing, the installed Appium version (1.6.2) from the above procedure doesn’t work properly with Cerberus. Only the 1.6.3-SNAPSHOT version was able to correctly start application. The following commands will help you to install the latest version of Appium (extracted from the official documentation):

      git clone https://github.com/appium/appium.git
      cd appium
      npm install -g mocha
      npm install -g gulp
      npm install -g gulp-cli
      npm install
      gulp transpile
Application sign configuration

The latest version of Appium uses the appium-xcuitest-driver which depend on the Web Driver Agent that need to be deployed on the tested device. Thus, the Appium server’s host needs to be configured to be allowed to deploy application on tested device.

Appium server’s host must:

  1. Have its associated Apple account registered to a Apple Team Development

  2. Have downloaded the iOS Development signing identity associated to the registered Apple Team Development

  3. Have downloaded a provisioning profile associated to the registered Apple Team Development that allow:

    • at least the Web Driver Agent application (identified by the com.facebook.WebDriverAgentLib bundle identifier)

    • the tested device to install the Web Driver Agent application

Once all of these previous prerequisities are met, then create a appium.xcconfig file and fill it with the following lines (where <Team ID> is your Development Team identifier):

DEVELOPMENT_TEAM = <Team ID>
CODE_SIGN_IDENTITY = iPhone Developer

This file will be used further by execution. Look at the Run section for more details.

Run

Run Appium server can differ following the way you installed it.

Installation from npm

If Appium has been installed from npm, then simply starts Appium server by executing:

appium
Installation from Appium sources

If Appium has been installed from its sources, we encourage to create an executable file to start and configure Appium server more easily. Then:

  1. Create a appium file and fill it with the following lines

    #!/bin/bash
    cd /path/to/appium/sources && node . "$@"
  2. Make this file executable

    chmod +x /path/to/the/appium/file
  3. Locate the root directory of this executable file and add it to your PATH variable by adding this line to your ~/.bash_profile (or any terminal session start) file:

    export PATH=/path/to/the/appium/file/root/directory:$PATH
  4. Restart your terminal session

  5. Start Appium server by executing

    appium
Note for IOS application testing

As viewed from previous section, Appium has to deal with Apple application sign. This could be done by sending the xcodeConfigFile capability to the Appium server.

But you may want to use the same value for any request, because the Apple Development Team is often unique within an organization. It could be the same for the realDeviceLogger capability because Appium can always using deviceconsole as real device logger.

This can be achieved by starting the Appium server with the --default-capabilities option and giving it the list of default capabilities. For maintenance reason, we recommend to delegate definition of the list of capabilities into a JSON file as the following:

  1. Create a file named common.caps (for instance)

  2. Fill it with your default capabilities

    {
        "xcodeConfigFile": "/path/to/appium.xcconfig",
    	"realDeviceLogger": "/usr/local/lib/node_modules/deviceconsole/deviceconsole"
    }
  3. Then start Appium server by executing

    appium --default-capabilities /path/to/common.caps

27.2.3. Client use

The following section will show different use cases to connect to the Appium server.

Execute mobile test case with Cerberus

Once you wrote your test case, Cerberus can execute it to the desired mobile by configuring the associated Robot

Inside Cerberus, open the Robot page (Run → Robot), and, depending on the application type, fill the Robot with the following configuration:

Android

Robot definition

Robot capabilities

Note
Values are given as example. feel free to modify them according to your needs.
IOS

Robot definition

Robot capabilities

Note

Values are given as example. feel free to modify them according to your needs.

The two last capabilities xcodeConfigFile and realDeviceLogger are not necessary if given at Appium startup. See the previous section for more details.

Inspection

Inspection is used to locate application’s element by identifier, XPath, etc. Theses values can so be use inside Cebrerus to describe automated test cases.

Inspection can be done by using the Appium client interface.

Installation

Install latest client from the official page.

Configuration

Appium client interface has to be configured to be only used for inspection. to have application’s element XPath for instance):

From the General settings menu:

  • Fill the Server address input field with the Appium server address

  • Fill the Port input field with the Appium server port

  • Unable the Use Remote Server option

General settings

For Android case, open the Android settings menu and:

  • Fill the App Path with the absolute path (or URL) of the application APK

  • Fill the Platform Name by Android

  • Fill the Automation Name by Appium

  • Fill the Platform Version by your device platform version

  • Fill the Device Name by your device name

Android settings

For IOS case, open the IOS settings menu and:

  • Fill the App Path with the absolute path (or URL) of the application IPA

  • Fill the Force device input filed by your device name

  • Fill the Platform version input field by your platform version. It must be lower or equal than your Xcode SDK supported version (for instance, 10.1 by using Xcode 8).

  • Fill the UDID input field by your device’s UDID number

IOS settings

Run

Once Appium client is correctly configured, simply click on the Android or IOS radio button following the application definition and then click on the Inspector button.

Appium Inspector

Title Link

List of Appium server capabilities

https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md

27.3. Sikuli

Unresolved directive in documentation_en.adoc - include::include/en/installation_externaltools_sikuli_en.adoc[]

27.4. Cloud

For Web and Mobile testing, Cerberus can be intefaced with cloud-based testing tool to avoid to manage complexity of robot farm management. Multiple combination of operating system, browser and version are available.

In the Cerberus demo integration chain, functionnal tests are executed through BrowserStack, that allow to validate the regression for each commit.

Browserstack

To run your tests on BrowserStack Automate, you must configure a Robot in Cerberus with your BrowserStack account information.

Maintenance

Maintenance introduction

FR Something is incorrect/missing in this section? Feel free to submit modification.

28. Monitor Cerberus performance

Maintenance monitoring Cerberus

FR Something is incorrect/missing in this section? Feel free to submit modification.

29. Clean Database

Maintenance Purge Database

FR Something is incorrect/missing in this section? Feel free to submit modification.

30. Upgrade Cerberus Version

Maintenance Upgrade Cerberus Version

FR Something is incorrect/missing in this section? Feel free to submit modification.