Prerequisites

STEP requires at least Java 8 installed in order to run. Depending on your platform, make sure to install at least Java JDK 8 on the machine(s) running STEP component(s).

Installation

Database

Follow instructions at : MongoDB documentation

Note: Since MongoDB version 6.3 installation must be done without the "MongoDB compas" GUI:

1528373203739-989.png

Configuration

If you want to tune your MongoDB instance, you will find all necessary informations on the official website at : MongoDB configuration and maintenance.

Activate authentification

Note: this procedure works for MongoDB server version < 4.0

For activating the authentification between the controller and the MongoDB server, the following actions have to be taken:

  • Change the authentication schema of the database:
    • If needed, restart the mongoDB server without authentication (adding the --noauth option to the startup script)
    • Connect to the mongo database and run the following script:

var schema = db.system.version.findOne({"_id" : "authSchema"})
schema.currentVersion = 3
db.system.version.save(schema)

  • Restart the MongoDB server
  • Create your user on the step database:

use step;
db.createUser({ user: "myUser", pwd: "myPassword", roles: [{ role: "readWrite", db: "step"}, { role: "readWrite", db: "step-enterprise"}]})

  • Restart the MongoDB server with authentication enabled (add the --auth option to the startup script)
  • Add the following properties to the .../conf/step.properties file:

db.username=myUser
db.password=myPassword

Installation as a Service

In order to install the controller as a Windows service, follow below steps :

  • download nssm at https://nssm.cc/download
  • open a new command prompte as Administrator  and navigate to the nssm executable location
  • execute the following command : 
nssm install
  • nssm gui will open, you can now specify the "startMongo.bat" location (usually located into the Controller bin folder) and the service name, then click on "Install service" :

1519652803326-179.png

  • You should then be prompted that the service installation has been successful :

1519652832668-922.png

  • you can double-check into Windows service list that the service has been properly installed and then you can start it :

1519652885358-880.png

Controller

Controller latest version can be downloaded from our Github repository at : STEP.

You can then extract the zip file with any unarchiver tool that support the zip format.

Folder Structure

Below the description of the Controller structure folder :

controller/
├── bin  : contains startup scripts
├── conf : contains configurations files
├── data : contains demo scripts and testing data
├── ext  : default location for external software binaries
├── lib  : contains dependencies libraries
└── log  : default location for the log files

Configuration

Configuration files can be found under the controller/conf folder and contains the following :

conf/
├── QuotaManagerConfig.xml
└── step.properties

Main configuration file that needs to be tuned is step.properties, other ones can be left untouched. You will have to amend this file in the following way :

  • port = <port_to_access_controller_gui>
  • grid.port = <port_for_agents_to_access_the_controller>
  • db.host = <mongo_hostname_or_ip>
  • db.port = <mongo_port>

For example :

  • port = 8080 -> Controller GUI will be accesible on port 8080
  • grid.port = 8081 -> Agents will connect to the Controller on port 8081
  • db.host = 127.0.0.1 -> Controller will try to access to MongoDB running on localhost
  • db.port = 27017 -> Controller will try to access to MongoDB on port 27017

Configuration placeholders (advanced)

Placeholders can be used in step.properties to define dynamic values that have to be set at startup outside the configuration file.

For instance, you might want to set the port of the GUI at startup. You could achieve this using a placeholder like this:

  • port = ${myPort}

and set the variable myPort in the startup script startController.bat(sh|command): 

"%JAVA_PATH%java.exe" %JAVA_OPTS% -cp "..\lib\*;" step.controller.ControllerServer -config=../conf/step.properties -myPort=8080

Startup

Startup scripts can be found under controller/bin and contains the following :

bin/
├── logback.xml
├── startController.bat
├── startController.command
├── startController.sh
├── startMongo.bat
├── startMongo.command
└── startMongo.sh

There are convenients scripts in order to start MongoDB too, you can use them once you have MongoDB installed and set in your path.
Warning : before trying to start the Controller, make sure Java binaries are set in your system path !

Depending on your platform, they are various ways to start the Controller :

  • Windows
    execute startController.bat
  • Linux
    make startController.sh executable and execute it
  • Mac OS
    make startController.command executable and execute it.

The web application should now be available on your host on the port you defined in the configuration file (for example at http://localhost:8080)
You will be then prompted for login information, default is admin // init :

LoginScreen.png

You can now see the Controller interface, by default opened on the "Plan" tab :

PlanTab.png

Log verbosity

You can easily change the logging verbosity by tweaking the "root" log level present in the file logback.xml. Below an example with the root log level verbosity set to "error" :

<!--
    (C) Copyright 2016 Jerome Comte and Dorian Cransac
    
    This file is part of STEP
    
    STEP is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    STEP is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.
    
    You should have received a copy of the GNU Affero General Public License
    along with STEP.  If not, see <http://www.gnu.org/licenses/>.
 -->

<configuration scan="true">
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
 <file>../log/controller.log</file>
 <encoder>
  <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
 </encoder>
 <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
     <fileNamePattern>../log/controller.%d{yyyy-MM-dd}.log</fileNamePattern>
     <maxHistory>30</maxHistory>
   </rollingPolicy>
</appender>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
 <encoder>
  <pattern>%msg%n</pattern>
 </encoder>
</appender>
<logger name="org.lightcouch" level="error" />
<!-- <logger name="io.djigger...." level="debug" /> -->

<root level="error">
 <appender-ref ref="STDOUT" />
 <appender-ref ref="FILE" />
</root>
</configuration>

Installation as a Service

In order to install the controller as a Windows service, follow below steps :

  • download nssm at https://nssm.cc/download
  • open a new command prompte as Administrator  and navigate to the nssm executable location
  • execute the following command : 
nssm install
  • nssm gui will open, you can now specify the "startController.bat" location and the service name, then click on "Install service" :

1519652093937-589.png

  • You should then be prompted that the service installation has been successful :

1519652162263-729.png

  • you can double-check into Windows service list that the service has been properly installed and then you can start it :

1519652292826-654.png

Maintenance

Running process

Depending on your platform, they are various ways to check if the Controller is running :

  • Windows
    open the Task Manager and look for the Java processes
  • Linux
    execute the following command as : ps -efl | grep ControllerServer. You should end up with the PID of the running process
  • Mac OS
     ????

Log file

The Controller log file will be created on first startup under the log folder. (You can change the log file location by editing the bin/logback.xml file). A successfull startup should display the following entry into the log file :

2017-09-26 02:02:11,371 INFO [main] o.e.j.u.log [Log.java:186] Logging initialized @1068ms
2017-09-26 02:02:12,046 INFO [main] o.r.Reflections [Reflections.java:229] Reflections took 560 ms to scan 13 urls, producing 124 keys and 413 values
2017-09-26 02:02:12,241 INFO [main] o.m.d.cluster [SLF4JLogger.java:71] Cluster created with settings {hosts=[mongo:27017], mode=SINGLE, requiredClusterType=UNKNOWN, serverSelectionTimeout='30000 ms', maxWaitQueueSize=500}
2017-09-26 02:02:12,278 INFO [main] o.m.d.cluster [SLF4JLogger.java:71] Cluster created with settings {hosts=[mongo:27017], mode=SINGLE, requiredClusterType=UNKNOWN, serverSelectionTimeout='30000 ms', maxWaitQueueSize=500}
2017-09-26 02:02:12,464 INFO [cluster-ClusterId{value='59c9b524133ae60008eec74f', description='null'}-mongo:27017] o.m.d.connection [SLF4JLogger.java:71] Opened connection [connectionId{localValue:2, serverValue:2}] to mongo:27017
2017-09-26 02:02:12,470 INFO [cluster-ClusterId{value='59c9b524133ae60008eec74f', description='null'}-mongo:27017] o.m.d.cluster [SLF4JLogger.java:71] Monitor thread successfully connected to server with description ServerDescription{address=mongo:27017, type=STANDALONE, state=CONNECTED, ok=true, version=ServerVersion{versionList=[3, 4, 9]}, minWireVersion=0, maxWireVersion=5, maxDocumentSize=16777216, roundTripTimeNanos=3533336}
2017-09-26 02:02:12,491 INFO [cluster-ClusterId{value='59c9b524133ae60008eec74e', description='null'}-mongo:27017] o.m.d.connection [SLF4JLogger.java:71] Opened connection [connectionId{localValue:1, serverValue:1}] to mongo:27017
2017-09-26 02:02:12,498 INFO [cluster-ClusterId{value='59c9b524133ae60008eec74e', description='null'}-mongo:27017] o.m.d.cluster [SLF4JLogger.java:71] Monitor thread successfully connected to server with description ServerDescription{address=mongo:27017, type=STANDALONE, state=CONNECTED, ok=true, version=ServerVersion{versionList=[3, 4, 9]}, minWireVersion=0, maxWireVersion=5, maxDocumentSize=16777216, roundTripTimeNanos=6662765}
2017-09-26 02:02:12,900 INFO [main] o.m.d.connection [SLF4JLogger.java:71] Opened connection [connectionId{localValue:3, serverValue:3}] to mongo:27017
2017-09-26 02:02:14,453 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:110] Searching for artefacts of type 'CallFunction' to be migrated...
2017-09-26 02:02:14,456 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:139] Migrated 0 artefacts of type 'CallFunction'
2017-09-26 02:02:14,456 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:143] Searching for artefacts of type 'FunctionGroup' to be migrated...
2017-09-26 02:02:14,458 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:166] Migrated 0 artefacts of type 'FunctionGroup'
2017-09-26 02:02:14,458 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:143] Searching for artefacts of type 'CallFunction' to be migrated...
2017-09-26 02:02:14,459 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:166] Migrated 0 artefacts of type 'CallFunction'
2017-09-26 02:02:16,210 INFO [main] o.r.c.MeasurementAccessor [MeasurementAccessor.java:74] Initializing db with address=mongo:27017, credentials=[]
2017-09-26 02:02:16,210 INFO [main] o.m.d.cluster [SLF4JLogger.java:71] Cluster created with settings {hosts=[mongo:27017], mode=SINGLE, requiredClusterType=UNKNOWN, serverSelectionTimeout='30000 ms', maxWaitQueueSize=500}
2017-09-26 02:02:16,212 INFO [main] o.m.d.cluster [SLF4JLogger.java:71] Cluster description not yet available. Waiting for 30000 ms before timing out
2017-09-26 02:02:16,218 INFO [cluster-ClusterId{value='59c9b528133ae60008eec75c', description='null'}-mongo:27017] o.m.d.connection [SLF4JLogger.java:71] Opened connection [connectionId{localValue:4, serverValue:6}] to mongo:27017
2017-09-26 02:02:16,219 INFO [cluster-ClusterId{value='59c9b528133ae60008eec75c', description='null'}-mongo:27017] o.m.d.cluster [SLF4JLogger.java:71] Monitor thread successfully connected to server with description ServerDescription{address=mongo:27017, type=STANDALONE, state=CONNECTED, ok=true, version=ServerVersion{versionList=[3, 4, 9]}, minWireVersion=0, maxWireVersion=5, maxDocumentSize=16777216, roundTripTimeNanos=559924}
2017-09-26 02:02:16,639 INFO [main] o.r.Reflections [Reflections.java:229] Reflections took 270 ms to scan 13 urls, producing 124 keys and 413 values
2017-09-26 02:02:16,861 INFO [main] o.e.j.s.Server [Server.java:327] jetty-9.2.17.v20160517
2017-09-26 02:02:18,048 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.ServletContextHandler@acd3460{/,null,AVAILABLE}
2017-09-26 02:02:18,068 INFO [main] o.e.j.s.ServerConnector [AbstractConnector.java:266] Started ServerConnector@5bba9949{HTTP/1.1}{0.0.0.0:8081}
2017-09-26 02:02:18,069 INFO [main] o.e.j.s.Server [Server.java:379] Started @7768ms
2017-09-26 02:02:18,208 WARN [main] o.e.j.s.h.ContextHandler [ContextHandler.java:1344] o.e.j.s.h.ContextHandler@206bd7a0{/,null,null} contextPath ends with /
2017-09-26 02:02:18,214 WARN [main] o.e.j.s.h.ContextHandler [ContextHandler.java:1344] o.e.j.s.h.ContextHandler@5a31abe9{/,null,null} contextPath ends with /
2017-09-26 02:02:18,216 WARN [main] o.e.j.s.h.ContextHandler [ContextHandler.java:1344] o.e.j.s.h.ContextHandler@2dacda9a{/,null,null} contextPath ends with /
2017-09-26 02:02:18,275 INFO [main] o.q.i.StdSchedulerFactory [StdSchedulerFactory.java:1184] Using default implementation for ThreadExecutor
2017-09-26 02:02:18,299 INFO [main] o.q.c.SchedulerSignalerImpl [SchedulerSignalerImpl.java:61] Initialized Scheduler Signaller of type: class org.quartz.core.SchedulerSignalerImpl
2017-09-26 02:02:18,302 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:240] Quartz Scheduler v.2.2.1 created.
2017-09-26 02:02:18,304 INFO [main] o.q.s.RAMJobStore [RAMJobStore.java:155] RAMJobStore initialized.
2017-09-26 02:02:18,307 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:305] Scheduler meta-data: Quartz Scheduler (v2.2.1) 'QuartzScheduler' with instanceId 'NON_CLUSTERED'
  Scheduler class: 'org.quartz.core.QuartzScheduler' - running locally.
  NOT STARTED.
  Currently in standby mode.
  Number of jobs executed: 0
  Using thread pool 'org.quartz.simpl.SimpleThreadPool' - with 10 threads.
  Using job-store 'org.quartz.simpl.RAMJobStore' - which does not support persistence. and is not clustered.

2017-09-26 02:02:18,308 INFO [main] o.q.i.StdSchedulerFactory [StdSchedulerFactory.java:1339] Quartz scheduler 'QuartzScheduler' initialized from an externally provided properties instance.
2017-09-26 02:02:18,308 INFO [main] o.q.i.StdSchedulerFactory [StdSchedulerFactory.java:1343] Quartz scheduler version: 2.2.1
2017-09-26 02:02:18,312 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:2311] JobFactory set to: step.core.scheduler.ExecutionJobFactory@153409b8
2017-09-26 02:02:18,313 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:575] Scheduler QuartzScheduler_$_NON_CLUSTERED started.
2017-09-26 02:02:18,341 INFO [main] o.e.j.s.Server [Server.java:327] jetty-9.2.17.v20160517
2017-09-26 02:02:19,100 INFO [main] o.e.j.w.StandardDescriptorProcessor [StandardDescriptorProcessor.java:297] NO JSP Support for /rtm, did not find org.eclipse.jetty.jsp.JettyJspServlet
2017-09-26 02:02:19,289 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.w.WebAppContext@9825465{/rtm,file:/tmp/jetty-0.0.0.0-8080-rtm-2.0.3.war-_rtm-any-4312820959754652971.dir/webapp/,AVAILABLE}{../ext/rtm-2.0.3.war}
2017-09-26 02:02:19,290 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.h.ContextHandler@206bd7a0{/scripteditor,null,AVAILABLE}
2017-09-26 02:02:19,290 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.h.ContextHandler@5a31abe9{/seleniumplugin,null,AVAILABLE}
2017-09-26 02:02:19,291 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.h.ContextHandler@2dacda9a{/jmeterplugin,null,AVAILABLE}
2017-09-26 02:02:19,645 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.ServletContextHandler@36cf6377{/rest,null,AVAILABLE}
2017-09-26 02:02:19,646 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.h.ContextHandler@2befb16f{/,null,AVAILABLE}
2017-09-26 02:02:19,647 INFO [main] o.e.j.s.h.ContextHandler [ContextHandler.java:744] Started o.e.j.s.ServletContextHandler@3151277f{/files,null,AVAILABLE}
2017-09-26 02:02:19,647 INFO [main] o.e.j.s.ServerConnector [AbstractConnector.java:266] Started ServerConnector@2d117280{HTTP/1.1}{0.0.0.0:8080}                                                                                                            2017-09-26 02:02:19,648 INFO [main] o.e.j.s.Server [Server.java:379] Started @9347ms

Agent

Agent latest version can be downloaded from our Github repository at : STEP.

You can then extract the zip file with any unarchiver tool that support the zip format.

Folder Structure

Below the description of the Agent structure folder :

agent/
├── bin  : contains startup scripts
├── conf : contains configurations files
├── ext  : default location for external software binaries and libraries
├── lib  : contains dependencies libraries
└── log  : default location for the log files

Configuration

Configuration files can be found under the agent/conf folder and contains the following :

conf/
├── AgentConf.json

Only configuration file that needs to be tuned is AgentConf.json You will have to amend this file in the following way :

  • "gridHost":"<url_to_access_controller_grid>",

For example :

  • "gridHost":"http://controller:8081" -> Means that the Agent will try to connect to the port 8081 of the host called controller

You can also define the agent token capacity according to the ressource allowed to each agent by setting up the capacity value :

  • "capacity": <token_number>

Keep in mind that the token number represent the number of parallel executions that will be allowed to run on the machine where the agent is installed.

For example :

  • "capacity":200 -> Means that maximum 200 executions can run in parallel on this agent

Configuration placeholders (advanced)

Placeholders can be used in AgentConf.json to define dynamic values that have to be set at startup outside the configuration file.

For instance, you might want to set the gridHost at startup. You could achieve this using a placeholder like this in your AgentConf.json:

  • "gridHost":"${myGridHost}",

and set the variable myGridHost in the startup script startAgent.bat(sh|command): 

"%JAVA_PATH%java.exe" %JAVA_OPTS% -cp "..\lib\*;" step.controller.ControllerServer -config=../conf/step.properties -myGridHost=http://mygridhost.net:8081

Give an agent a specific type

It is possible to configure an agent to match a "type" using the following configuration subsection in the AgentConf.json file :

"tokenGroups":[
{"capacity":1,
"tokenConf":{
 "attributes":{"AGENT_TYPE" : "DEV"},
 "properties":{}}
}
],

AGENT_TYPE can be used to route the workload on specific machines hosting this agent, enabling the ability to choose where to run test plans (see this link)

Startup

Startup scripts can be found under agent/bin and contains the following :

bin
├── logback.xml
├── startAgent.bat
├── startAgent.command
└── startAgent.sh

Warning : before trying to start the Agent, make sure Java binaries are set in your system path !

Depending on your platform, they are various ways to start the Agent :

  • Windows
    execute startAgent.bat
  • Linux
    make startAgent.sh executable and execute it
  • Mac OS
    make startAgent.command executable and execute it.

Going to the Controller inteface under the "Grid" tab will show you that your agent is now connected and ready to receive requests from the Controller :

GridTab.png

Installation as a Service

In order to install the agent as a Windows service, follow below steps :

  • download nssm at https://nssm.cc/download
  • open a new command prompte as Administrator and navigate to the nssm executable location
  • execute the following command : 
nssm install
  • nssm gui will open, you can now specify the "startAgent.bat" location and the service name, then click on "Install service" :

1519652461740-167.png

  • You should then be prompted that the service installation has been successful :

1519652506735-767.png

  • you can double-check into Windows service list that the service has been properly installed and then you can start it :

1519652560790-758.png

Maintenance

Running process

Depending on your platform, they are various ways to check if the Agent is running :

  • Windows
    open the Task Manager and look for the Java processes
  • Linux
    execute the following command as : ps -efl | grep Agent. You should end up with the PID of the running process
  • Mac OS
     ????

Log file

The Agent log file will be created on first startup under the log folder. (You can change the log file location by editing the bin/logback.xml file). A successful startup should display the following entry into the log file:

2017-09-26 13:22:40,639 INFO [main] o.e.j.s.Server [Server.java:379] Started @1326ms 

Backup

Assuming you are running MongoDB with the default settings (host localhost, port 27017, no authentication), you can perform backups following below instructions.

Complete backup

To perform a full backup of the STEP database, use the following command to output the backup to the backup folder:

mongodump -d step -o backup

If you prefer create a compressed archive, use the following :

mongodump -d step --gzip --archive=backup.gzip

You should see the following output which confirms the backup succeeded :

mongodump -d step -o backup
2017-10-05T10:45:39.677+0000    writing step.functions to
2017-10-05T10:45:39.677+0000    writing step.reports to
2017-10-05T10:45:39.677+0000    writing step.artefacts to
2017-10-05T10:45:39.677+0000    writing step.views to
2017-10-05T10:45:39.678+0000    done dumping step.functions (6 documents)
2017-10-05T10:45:39.678+0000    writing step.measurements to
2017-10-05T10:45:39.678+0000    done dumping step.reports (3 documents)
2017-10-05T10:45:39.678+0000    writing step.users to
2017-10-05T10:45:39.679+0000    done dumping step.measurements (2 documents)
2017-10-05T10:45:39.679+0000    writing step.controllerlogs to
2017-10-05T10:45:39.679+0000    done dumping step.users (1 document)
2017-10-05T10:45:39.679+0000    writing step.executions to
2017-10-05T10:45:39.680+0000    done dumping step.artefacts (6 documents)
2017-10-05T10:45:39.680+0000    done dumping step.views (3 documents)
2017-10-05T10:45:39.680+0000    done dumping step.controllerlogs (1 document)
2017-10-05T10:45:39.681+0000    done dumping step.executions (1 document)

Partial backup

To perform a backup of a specific STEP collection, use the following command :

mongoexport -d step -c <collection_name> -o <collection_name>.json

To display the available collections for backup, connect to you mongo instance and execute the following :

> use step
switched to db step
> db.getCollectionNames()
[
        "artefacts",
        "controllerlogs",
        "executions",
        "functions",
        "measurements",
        "reports",
        "users",
        "views"
]
> exit

Backup your work (Keywords and Test Plans)

In order to perform a backup of your Keywords and your Test Plans, use the following command :

mongoexport -d step -c functions -o functions.json
mongoexport -d step -c artefacts -o artefacts.json

This will not dump the Test Plan executions nor their associated performance metrics !

Backup reports based on executions in a time window

As the reports collections may grow very quickly with the number of tests executions, you may want to export only some of the reports associated with executions which ran into a defined time frame.

For this, we need first to export the executions ids in the defined time frame, for example here the time frame is defined from the 2018/06/06 at 2 PM to the 2018/06/07 at 3 PM.

Open a terminal and execute the following command (make sure to replace the start times with the values you need) : 

mongo localhost/step --quiet --eval "db.executions.find({ '$and': [{'startTime': {'$gt': NumberLong(ISODate('2018-06-06T14:00:00'))}}, {'startTime': {'$lt' : NumberLong(ISODate('2018-06-07T15:00:00'))}}] }).map(e => '\''.concat(e._id.valueOf(),'\'')).toString()" > executions_ids

This will output the execution ids into the file "executions_ids" and its content should look like :

'5b17e8fe064db31178a3c5a1','5b17e936064db31178a3c5f5','5b17e961064db31178a3c661','5b18e8a6bd6ea136547043ee','5b18e8b8bd6ea13654704421','5b18e8bcbd6ea13654704463' 

Now that you have the executions ids, you can execute the below command in a terminal by replacing the executions ids list with the one you just exported :

mongoexport -d step -c reports -q "{'executionID': {'$in': ['5b17e8fe064db31178a3c5a1','5b17e936064db31178a3c5f5','5b17e961064db31178a3c661','5b18e8a6bd6ea136547043ee','5b18e8b8bd6ea13654704421','5b18e8bcbd6ea13654704463']}}" -o reports.csv 

This will output to the file "reports.csv" the reports associated with the executions which have ran in the define time window.

Restore

Assuming you are running MongoDB with the default settings (host localhost, port 27017, no authentication) and that an archive previsouly created using the backup procedure exists, use below instructions to restore your database.

Complete Restore

To fully restore a STEP database from a backup folder, use the following command :

mongorestore --drop -d step backup

If you prefer to restore the database from a compressed archive previously created, use the following :

mongorestore --drop -d step --gzip --archive=backup.gzip

Warning : using the --drop flag will cause the existing content to be deleted ! You should see the following output which confirms the restore succeeded :

mongorestore --drop backup/
2017-10-05T10:48:29.070+0000    preparing collections to restore from
2017-10-05T10:48:29.089+0000    reading metadata for step.functions from backup/step/functions.metadata.json
2017-10-05T10:48:29.098+0000    reading metadata for step.artefacts from backup/step/artefacts.metadata.json
2017-10-05T10:48:29.148+0000    reading metadata for step.executions from backup/step/executions.metadata.json
2017-10-05T10:48:29.156+0000    reading metadata for step.views from backup/step/views.metadata.json
2017-10-05T10:48:29.265+0000    restoring step.functions from backup/step/functions.bson
2017-10-05T10:48:29.442+0000    restoring step.artefacts from backup/step/artefacts.bson
2017-10-05T10:48:29.584+0000    restoring step.executions from backup/step/executions.bson
2017-10-05T10:48:29.719+0000    restoring step.views from backup/step/views.bson
2017-10-05T10:48:29.720+0000    no indexes to restore
2017-10-05T10:48:29.720+0000    finished restoring step.functions (6 documents)
2017-10-05T10:48:29.720+0000    no indexes to restore
2017-10-05T10:48:29.720+0000    restoring indexes for collection step.executions from metadata
2017-10-05T10:48:29.721+0000    finished restoring step.artefacts (6 documents)
2017-10-05T10:48:29.721+0000    restoring indexes for collection step.views from metadata
2017-10-05T10:48:29.785+0000    reading metadata for step.reports from backup/step/reports.metadata.json
2017-10-05T10:48:30.113+0000    finished restoring step.executions (1 document)
2017-10-05T10:48:30.157+0000    reading metadata for step.measurements from backup/step/measurements.metadata.json
2017-10-05T10:48:30.255+0000    finished restoring step.views (3 documents)
2017-10-05T10:48:30.373+0000    restoring step.reports from backup/step/reports.bson
2017-10-05T10:48:30.382+0000    reading metadata for step.users from backup/step/users.metadata.json
2017-10-05T10:48:30.498+0000    restoring step.measurements from backup/step/measurements.bson
2017-10-05T10:48:30.565+0000    reading metadata for step.controllerlogs from backup/step/controllerlogs.metadata.json
2017-10-05T10:48:30.565+0000    restoring indexes for collection step.reports from metadata
2017-10-05T10:48:30.699+0000    restoring step.users from backup/step/users.bson
2017-10-05T10:48:30.699+0000    restoring indexes for collection step.measurements from metadata
2017-10-05T10:48:30.807+0000    restoring step.controllerlogs from backup/step/controllerlogs.bson
2017-10-05T10:48:31.235+0000    finished restoring step.reports (3 documents)
2017-10-05T10:48:31.316+0000    finished restoring step.measurements (2 documents)
2017-10-05T10:48:31.316+0000    no indexes to restore
2017-10-05T10:48:31.316+0000    finished restoring step.controllerlogs (1 document)
2017-10-05T10:48:31.316+0000    no indexes to restore
2017-10-05T10:48:31.316+0000    finished restoring step.users (1 document)
2017-10-05T10:48:31.316+0000    done

Partial restore

To perform a restore of a specific STEP collection, use the following command :

mongoimport --drop -d step -c <collection_name> <collection_name>.json

Warning : using the --drop flag will cause the existing collection content to be deleted !

Restore your work (Keywords and Test Plans)

You can restore your Keywords and Test Plans from a previous backup using the following commands :

mongoimport --drop -d step -c functions functions.json
mongoimport --drop -d step -c artefacts artefacts.json

Purge / Maintenance

Complete purge

If your database grows too much and you want to get rid of all the old executions and performance metrics, you can drop the whole database then re-import only your Keywords and Test Plan, which is the fastest way to execute a purge.
Follow below steps :

> use step
switched to db step
> db.dropDatabase();
{ "dropped" : "step", "ok" : 1 }
> exit

Keep only current month results

Idea is to execute a backup of the current months collections executions, reports and measurements in order to clean up the database from the previous executions. Let's say we are currently in October and that we want to remove all data concerning executions done before that month. We will first export the executions executed from 1st of October.

  • First get the timestamp as NumberLong format we will use to perform our queries. Connect to your database and run the following command :

> NumberLong(ISODate("2017-10-01"))
NumberLong("1506816000000") # This is the result we need
> exit # Exit the database

  • We can now export the executions, reports and measurements using following commands :

mongoexport -d step -c executions -q '{"startTime":{"$gt":NumberLong("1506816000000")}}' -o executions_gt_20171001.json
mongoexport -d step -c measurements -q '{"begin":{"$gt":NumberLong("1506816000000")}}' -o measurements_gt_20171001.json
mongoexport -d step -c reports -q '{"executionTime":{"$gt":NumberLong("1506816000000")}}' -o reports_gt_20171001.json

  • Execute a complete purge (do not forget to re-import your Keyword and Test Plans !)
  • Restore your last month executions by running following commands :

mongoimport -d step -c executions executions_gt_20171001.json
mongoimport -d step -c measurements measurements_gt_20171001.json
mongoimport -d step -c reports reports_gt_20171001.json

Export only 1 execution and its data

Sometimes you may want to backup only 1 test plan execution in order to keep it for later analysis. So first you need to gather the Execution ID of your test plan execution :

  • login to your STEP instance, go to the Executions tab and click to the execution you want to get the ID : 

ExecutionsTab.png

  • Now that you have the execution ID (in our example it is 59d4d8f9a63eaa00074f6dd0), you can export the executions and its data :
mongoexport -d step -c executions -q '{"_id":ObjectId("59d4d8f9a63eaa00074f6dd0")}' -o execution_59d4d8f9a63eaa00074f6dd0.json
# To export the measurement metrics :
mongoexport -d step -c measurements -q '{"eId":"59d4d8f9a63eaa00074f6dd0"}' -o measurements_59d4d8f9a63eaa00074f6dd0.json
# To export executions steps :
mongoexport -d step -c reports -q '{$or: [ { "parentID":ObjectId("59d4d8f9a63eaa00074f6dd0") }, { "executionID":"59d4d8f9a63eaa00074f6dd0" } ] }' -o reports_59d4d8f9a63eaa00074f6dd0.json

You can now restore the executions with its associated data using the following :

mongoimport -d step -c executions execution_59d4d8f9a63eaa00074f6dd0.json
mongoimport -d step -c measurements measurements_59d4d8f9a63eaa00074f6dd0.json
mongoimport -d step -c reports reports_59d4d8f9a63eaa00074f6dd0.json

Note that you can only restore the performance metrics or the functional results depending on your goal. To know which collections to restore use following table :

CollectionsFunctional resultsPerformance metrics
reportsmandatorymandatory
reportsmandatory

Execution.png

not mandatory
measurementsnot mandatorymandatory

Performance.png

Migration

Information related to the migration process has been moved to a dedicated page in the left menu.

Tags:
Created by David Stephan on 2019/01/16 09:59
     
Copyright © exense GmbH
v1.0