Show last authors
1 {{toc depth="4"/}}
2
3 = Prerequisites =
4
5 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).
6
7 = Installation =
8
9 == Database ==
10
11 Follow instructions at [[: MongoDB documentation>>url:https://docs.mongodb.com/master/administration/install-community/]]
12
13 (% class="wikigeneratedid" %)
14 Note: Since MongoDB version 6.3 installation must be done **without** the "MongoDB compas" GUI:
15
16 (% style="text-align:center" %)
17 [[image:1528373203739-989.png||height="405" width="521"]]
18
19 === Configuration ===
20
21 If you want to tune your MongoDB instance, you will find all necessary informations on the official website at : [[MongoDB configuration and maintenance>>url:https://docs.mongodb.com/master/administration/configuration-and-maintenance/]].
22
23 === Activate authentification ===
24
25 (% class="box warningmessage" %)
26 (((
27 Note: this procedure works for MongoDB server version < 4.0
28 )))
29
30 (% class="wikigeneratedid" %)
31 For activating the authentification between the controller and the MongoDB server, the following actions have to be taken:
32
33 * Change the authentication schema of the database:
34 ** If needed, restart the mongoDB server without authentication (adding the ~-~-noauth option to the startup script)
35 ** Connect to the mongo database and run the following script:
36
37 (% class="box" %)
38 (((
39 var schema = db.system.version.findOne({"_id" : "authSchema"})
40 schema.currentVersion = 3
41 db.system.version.save(schema)
42 )))
43
44 * Restart the MongoDB server
45 * Create your user on the step database:
46
47 (% class="box" %)
48 (((
49 use step;
50 db.createUser({ user: "**//myUser//**", pwd: "**//myPassword//**", roles: [{ role: "readWrite", db: "step"}, { role: "readWrite", db: "step-enterprise"}]})
51 )))
52
53 * Restart the MongoDB server with authentication enabled (add the ~-~-auth option to the startup script)
54 * Add the following properties to the ...**/conf/step.properties** file:
55
56 (% class="box" %)
57 (((
58 db.username=**//myUser//**
59 db.password=**//myPassword//**
60 )))
61
62 === Installation as a Service{{id name="mongo_service"/}} ===
63
64 In order to install the controller as a Windows service, follow below steps :
65
66 * download **nssm** at [[https:~~/~~/nssm.cc/download>>url:https://nssm.cc/download]]
67 * open a new command prompte as **Administrator ** and navigate to the nssm executable location
68 * execute the following command :
69
70 {{code}}
71 nssm install
72 {{/code}}
73
74 * **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"** :
75
76 (% style="text-align:center" %)
77 [[image:1519652803326-179.png||class="img-thumbnail" height="229" width="424"]]
78
79 * You should then be prompted that the service installation has been successful :
80
81 (% style="text-align:center" %)
82 [[image:1519652832668-922.png||class="img-thumbnail" height="144" width="310"]]
83
84 * you can double-check into Windows service list that the service has been properly installed and then you can start it :
85
86 (% style="text-align:center" %)
87 [[image:1519652885358-880.png||class="img-thumbnail" height="221" width="1132"]]
88
89 == Controller{{id name="controller"/}} ==
90
91 Controller latest version can be downloaded from our Github repository at : [[STEP>>https://github.com/exense/step/releases/latest]].
92
93 You can then extract the zip file with any unarchiver tool that support the zip format.
94
95 === Folder Structure ===
96
97 Below the description of the Controller structure folder :
98
99 (% class="box" %)
100 (((
101 controller/
102 ├── bin : contains startup scripts
103 ├── conf : contains configurations files
104 ├── data : contains demo scripts and testing data
105 ├── ext : default location for external software binaries
106 ├── lib : contains dependencies libraries
107 └── log : default location for the log files
108 )))
109
110 === Configuration{{id name="controller_conf"/}} ===
111
112 Configuration files can be found under the **controller/conf** folder and contains the following :
113
114 (% class="box" %)
115 (((
116 conf/
117 ├── QuotaManagerConfig.xml
118 └── step.properties
119 )))
120
121 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 :
122
123 * port = //<port_to_access_controller_gui>//
124 * grid.port = //<port_for_agents_to_access_the_controller>//
125 * db.host = //<mongo_hostname_or_ip>//
126 * db.port = //<mongo_port>//
127
128 For example :
129
130 * port = 8080 -> Controller GUI will be accesible on port 8080
131 * grid.port = 8081 -> Agents will connect to the Controller on port 8081
132 * db.host = 127.0.0.1 -> Controller will try to access to MongoDB running on localhost
133 * db.port = 27017 -> Controller will try to access to MongoDB on port 27017
134
135 ==== Configuration placeholders (advanced) ====
136
137 Placeholders can be used in **step.properties **to define dynamic values that have to be set at startup outside the configuration file.
138
139 For instance, you might want to set the port of the GUI at startup. You could achieve this using a placeholder like this:
140
141 * port = ${myPort}
142
143 and set the variable myPort in the startup script startController.bat(sh|command):
144
145 "%JAVA_PATH%java.exe" %JAVA_OPTS% -cp "..\lib\*;" step.controller.ControllerServer -config=../conf/step.properties **-myPort=8080**
146
147 === Startup{{id name="controller_restart"/}} ===
148
149 Startup scripts can be found under **controller/bin** and contains the following :
150
151 (% class="box" %)
152 (((
153 bin/
154 ├── logback.xml
155 ├── startController.bat
156 ├── startController.command
157 ├── startController.sh
158 ├── startMongo.bat
159 ├── startMongo.command
160 └── startMongo.sh
161 )))
162
163 There are convenients scripts in order to start MongoDB too, you can use them once you have MongoDB installed and set in your path.
164 Warning : before trying to start the Controller, make sure Java binaries are set in your system path !
165
166 Depending on your platform, they are various ways to start the Controller :
167
168 * **Windows**
169 *: execute startController.bat
170 * **Linux**
171 *: make startController.sh executable and execute it
172 * **Mac OS**
173 *: make startController.command executable and execute it.
174
175 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>>url:http://localhost:8080/]]**)
176 You will be then prompted for login information, default is **admin ~/~/ init** :
177
178 (% style="text-align:center" %)
179 [[image:LoginScreen.png||class="img-thumbnail" height="337" width="500"]]
180
181 You can now see the Controller interface, by default opened on the **"Plan"** tab :
182
183 (% style="text-align:center" %)
184 [[image:PlanTab.png||class="img-thumbnail" height="256" width="1000"]]
185
186 === Log verbosity ===
187
188 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"** :
189
190 {{code}}
191 <!--
192 (C) Copyright 2016 Jerome Comte and Dorian Cransac
193
194 This file is part of STEP
195
196 STEP is free software: you can redistribute it and/or modify
197 it under the terms of the GNU Affero General Public License as published by
198 the Free Software Foundation, either version 3 of the License, or
199 (at your option) any later version.
200
201 STEP is distributed in the hope that it will be useful,
202 but WITHOUT ANY WARRANTY; without even the implied warranty of
203 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
204 GNU Affero General Public License for more details.
205
206 You should have received a copy of the GNU Affero General Public License
207 along with STEP. If not, see <http://www.gnu.org/licenses/>.
208 -->
209 <configuration scan="true">
210 <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
211 <file>../log/controller.log</file>
212 <encoder>
213 <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
214 </encoder>
215 <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
216 <fileNamePattern>../log/controller.%d{yyyy-MM-dd}.log</fileNamePattern>
217 <maxHistory>30</maxHistory>
218 </rollingPolicy>
219 </appender>
220 <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
221 <encoder>
222 <pattern>%msg%n</pattern>
223 </encoder>
224 </appender>
225 <logger name="org.lightcouch" level="error" />
226 <!-- <logger name="io.djigger...." level="debug" /> -->
227
228 <root level="error">
229 <appender-ref ref="STDOUT" />
230 <appender-ref ref="FILE" />
231 </root>
232 </configuration>
233 {{/code}}
234
235 === Installation as a Service{{id name="controller_service"/}} ===
236
237 In order to install the controller as a Windows service, follow below steps :
238
239 * download **nssm** at [[https:~~/~~/nssm.cc/download>>url:https://nssm.cc/download]]
240 * open a new command prompte as **Administrator ** and navigate to the nssm executable location
241 * execute the following command :
242
243 {{code}}
244 nssm install
245 {{/code}}
246
247 * **nssm** gui will open, you can now specify the "**startController.bat**" location and the service name, then click on "**Install service"** :
248
249 (% style="text-align:center" %)
250 [[image:1519652093937-589.png||class="img-thumbnail" height="228" width="424"]]
251
252 * You should then be prompted that the service installation has been successful :
253
254 (% style="text-align:center" %)
255 [[image:1519652162263-729.png||class="img-thumbnail" height="146" width="325"]]
256
257 * you can double-check into Windows service list that the service has been properly installed and then you can start it :
258
259 (% style="text-align:center" %)
260 [[image:1519652292826-654.png||class="img-thumbnail" height="203" width="1132"]]
261
262 === Maintenance ===
263
264 ==== Running process ====
265
266 Depending on your platform, they are various ways to check if the Controller is running :
267
268 * **Windows**
269 *: open the Task Manager and look for the Java processes
270 * **Linux**
271 *: execute the following command as : ps -efl | grep ControllerServer. You should end up with the PID of the running process
272 * **Mac OS**
273 *: ????
274
275 ==== Log file ====
276
277 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 :
278
279 (% class="box" %)
280 (((
281 2017-09-26 02:02:11,371 INFO [main] o.e.j.u.log [Log.java:186] Logging initialized @1068ms
282 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
283 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}
284 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}
285 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
286 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}
287 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
288 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}
289 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
290 2017-09-26 02:02:14,453 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:110] Searching for artefacts of type 'CallFunction' to be migrated...
291 2017-09-26 02:02:14,456 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:139] Migrated 0 artefacts of type 'CallFunction'
292 2017-09-26 02:02:14,456 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:143] Searching for artefacts of type 'FunctionGroup' to be migrated...
293 2017-09-26 02:02:14,458 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:166] Migrated 0 artefacts of type 'FunctionGroup'
294 2017-09-26 02:02:14,458 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:143] Searching for artefacts of type 'CallFunction' to be migrated...
295 2017-09-26 02:02:14,459 INFO [main] s.i.InitializationPlugin [InitializationPlugin.java:166] Migrated 0 artefacts of type 'CallFunction'
296 2017-09-26 02:02:16,210 INFO [main] o.r.c.MeasurementAccessor [MeasurementAccessor.java:74] Initializing db with address=mongo:27017, credentials=[]
297 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}
298 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
299 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
300 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}
301 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
302 2017-09-26 02:02:16,861 INFO [main] o.e.j.s.Server [Server.java:327] jetty-9.2.17.v20160517
303 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}
304 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}
305 2017-09-26 02:02:18,069 INFO [main] o.e.j.s.Server [Server.java:379] Started @7768ms
306 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 /
307 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 /
308 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 /
309 2017-09-26 02:02:18,275 INFO [main] o.q.i.StdSchedulerFactory [StdSchedulerFactory.java:1184] Using default implementation for ThreadExecutor
310 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
311 2017-09-26 02:02:18,302 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:240] Quartz Scheduler v.2.2.1 created.
312 2017-09-26 02:02:18,304 INFO [main] o.q.s.RAMJobStore [RAMJobStore.java:155] RAMJobStore initialized.
313 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'
314 Scheduler class: 'org.quartz.core.QuartzScheduler' - running locally.
315 NOT STARTED.
316 Currently in standby mode.
317 Number of jobs executed: 0
318 Using thread pool 'org.quartz.simpl.SimpleThreadPool' - with 10 threads.
319 Using job-store 'org.quartz.simpl.RAMJobStore' - which does not support persistence. and is not clustered.
320
321 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.
322 2017-09-26 02:02:18,308 INFO [main] o.q.i.StdSchedulerFactory [StdSchedulerFactory.java:1343] Quartz scheduler version: 2.2.1
323 2017-09-26 02:02:18,312 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:2311] JobFactory set to: step.core.scheduler.ExecutionJobFactory@153409b8
324 2017-09-26 02:02:18,313 INFO [main] o.q.c.QuartzScheduler [QuartzScheduler.java:575] Scheduler QuartzScheduler_$_NON_CLUSTERED started.
325 2017-09-26 02:02:18,341 INFO [main] o.e.j.s.Server [Server.java:327] jetty-9.2.17.v20160517
326 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
327 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}
328 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}
329 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}
330 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}
331 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}
332 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}
333 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}
334 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
335 )))
336
337 == Agent ==
338
339 Agent latest version can be downloaded from our Github repository at : [[STEP>>https://github.com/exense/step/releases/latest]].
340
341 You can then extract the zip file with any unarchiver tool that support the zip format.
342
343 === Folder Structure ===
344
345 Below the description of the Agent structure folder :
346
347 (% class="box" %)
348 (((
349 agent/
350 ├── bin : contains startup scripts
351 ├── conf : contains configurations files
352 ├── ext : default location for external software binaries and libraries
353 ├── lib : contains dependencies libraries
354 └── log : default location for the log files
355 )))
356
357 === Configuration ===
358
359 Configuration files can be found under the **agent/conf** folder and contains the following :
360
361 (% class="box" %)
362 (((
363 conf/
364 ├── AgentConf.json
365 )))
366
367 Only configuration file that needs to be tuned is **AgentConf.json** You will have to amend this file in the following way :
368
369 * "gridHost"~://"<url_to_access_controller_grid>"//,
370
371 For example :
372
373 * "gridHost":"http:~/~/controller:8081" -> Means that the Agent will try to connect to the port 8081 of the host called //controller//
374
375 You can also define the agent token capacity according to the ressource allowed to each agent by setting up the //capacity// value :
376
377 * "capacity": //<token_number>//
378
379 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.
380
381 For example :
382
383 * "capacity":200 -> Means that maximum 200 executions can run in parallel on this agent
384
385 ==== Configuration placeholders (advanced) ====
386
387 Placeholders can be used in **AgentConf.json **to define dynamic values that have to be set at startup outside the configuration file.
388
389 For instance, you might want to set the gridHost at startup. You could achieve this using a placeholder like this in your AgentConf.json:
390
391 * "gridHost":"${myGridHost}",
392
393 and set the variable myGridHost in the startup script startAgent.bat(sh|command):
394
395 "%JAVA_PATH%java.exe" %JAVA_OPTS% -cp "..\lib\*;" step.controller.ControllerServer -config=../conf/step.properties **-myGridHost=http:~/~/mygridhost.net:8081**
396
397 ==== Give an agent a specific type ====
398
399 It is possible to configure an agent to match a "type" using the following configuration subsection in the AgentConf.json file :
400
401 (% class="box" %)
402 (((
403 "tokenGroups":[
404 {"capacity":1,
405 "tokenConf":{
406 "attributes":{"AGENT_TYPE" : "DEV"},
407 "properties":{}}
408 }
409 ],
410 )))
411
412 (% class="wikigeneratedid" %)
413 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>>http://docs.exense.ch/wiki/step/view/Versions/3.9.x/Plans/#HKeywordrouting:executiononspecificagents]])
414
415 === Startup{{id name="agent_restart"/}} ===
416
417 Startup scripts can be found under **agent/bin** and contains the following :
418
419 (% class="box" %)
420 (((
421 bin
422 ├── logback.xml
423 ├── startAgent.bat
424 ├── startAgent.command
425 └── startAgent.sh
426 )))
427
428 Warning : before trying to start the Agent, make sure Java binaries are set in your system path !
429
430 Depending on your platform, they are various ways to start the Agent :
431
432 * **Windows**
433 *: execute startAgent.bat
434 * **Linux**
435 *: make startAgent.sh executable and execute it
436 * **Mac OS**
437 *: make startAgent.command executable and execute it.
438
439 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 :
440
441 (% style="text-align:center" %)
442 [[image:GridTab.png||class="img-thumbnail" height="261" width="1000"]]
443
444 === Installation as a Service{{id name="agent_service"/}} ===
445
446 In order to install the agent as a Windows service, follow below steps :
447
448 * download **nssm** at [[https:~~/~~/nssm.cc/download>>url:https://nssm.cc/download]]
449 * open a new command prompte as **Administrator **and navigate to the nssm executable location
450 * execute the following command :
451
452 {{code}}
453 nssm install
454 {{/code}}
455
456 * **nssm** gui will open, you can now specify the "**startAgent.bat**" location and the service name, then click on "**Install service"** :
457
458 (% style="text-align:center" %)
459 [[image:1519652461740-167.png||class="img-thumbnail" height="228" width="424"]]
460
461 * You should then be prompted that the service installation has been successful :
462
463 (% style="text-align:center" %)
464 [[image:1519652506735-767.png||class="img-thumbnail" height="142" width="307"]]
465
466 * you can double-check into Windows service list that the service has been properly installed and then you can start it :
467
468 (% style="text-align:center" %)
469 [[image:1519652560790-758.png||class="img-thumbnail" height="201" width="1107"]]
470
471 === Maintenance ===
472
473 ==== Running process ====
474
475 Depending on your platform, they are various ways to check if the Agent is running :
476
477 * **Windows**
478 *: open the Task Manager and look for the Java processes
479 * **Linux**
480 *: execute the following command as : ps -efl | grep Agent. You should end up with the PID of the running process
481 * **Mac OS**
482 *: ????
483
484 ==== Log file ====
485
486 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:
487
488 (% class="box" %)
489 (((
490 2017-09-26 13:22:40,639 INFO [main] o.e.j.s.Server [Server.java:379] Started @1326ms
491 )))
492
493 = Backup =
494
495 Assuming you are running MongoDB with the default settings (host //localhost//, port //27017//, no authentication), you can perform backups following below instructions.
496
497 == Complete backup ==
498
499 To perform a full backup of the STEP database, use the following command to output the backup to the //backup// folder:
500
501 (% class="box" %)
502 (((
503 mongodump -d step -o backup
504 )))
505
506 If you prefer create a compressed archive, use the following :
507
508 (% class="box" %)
509 (((
510 mongodump -d step ~-~-gzip ~-~-archive=backup.gzip
511 )))
512
513 You should see the following output which confirms the backup succeeded :
514
515 (% class="box" %)
516 (((
517 mongodump -d step -o backup
518 2017-10-05T10:45:39.677+0000 writing step.functions to
519 2017-10-05T10:45:39.677+0000 writing step.reports to
520 2017-10-05T10:45:39.677+0000 writing step.artefacts to
521 2017-10-05T10:45:39.677+0000 writing step.views to
522 2017-10-05T10:45:39.678+0000 done dumping step.functions (6 documents)
523 2017-10-05T10:45:39.678+0000 writing step.measurements to
524 2017-10-05T10:45:39.678+0000 done dumping step.reports (3 documents)
525 2017-10-05T10:45:39.678+0000 writing step.users to
526 2017-10-05T10:45:39.679+0000 done dumping step.measurements (2 documents)
527 2017-10-05T10:45:39.679+0000 writing step.controllerlogs to
528 2017-10-05T10:45:39.679+0000 done dumping step.users (1 document)
529 2017-10-05T10:45:39.679+0000 writing step.executions to
530 2017-10-05T10:45:39.680+0000 done dumping step.artefacts (6 documents)
531 2017-10-05T10:45:39.680+0000 done dumping step.views (3 documents)
532 2017-10-05T10:45:39.680+0000 done dumping step.controllerlogs (1 document)
533 2017-10-05T10:45:39.681+0000 done dumping step.executions (1 document)
534 )))
535
536 == Partial backup ==
537
538 To perform a backup of a specific STEP collection, use the following command :
539
540 (% class="box" %)
541 (((
542 mongoexport -d step -c <collection_name> -o <collection_name>.json
543 )))
544
545 To display the available collections for backup, connect to you mongo instance and execute the following :
546
547 (% class="box" %)
548 (((
549 ~> use step
550 switched to db step
551 ~> db.getCollectionNames()
552 [
553 "artefacts",
554 "controllerlogs",
555 "executions",
556 "functions",
557 "measurements",
558 "reports",
559 "users",
560 "views"
561 ]
562 ~> exit
563 )))
564
565 == Backup your work (Keywords and Test Plans){{id name="work_backup"/}} ==
566
567 In order to perform a backup of your Keywords and your Test Plans, use the following command :
568
569 (% class="box" %)
570 (((
571 mongoexport -d step -c functions -o functions.json
572 mongoexport -d step -c artefacts -o artefacts.json
573 )))
574
575 This will not dump the Test Plan executions nor their associated performance metrics !
576
577 == Backup reports based on executions in a time window ==
578
579 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.
580
581 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.
582
583 Open a terminal and execute the following command (make sure to replace the start times with the values you need) :
584
585 (% class="box" %)
586 (((
587 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
588 )))
589
590 This will output the execution ids into the file "executions_ids" and its content should look like :
591
592 (% class="box" %)
593 (((
594 '5b17e8fe064db31178a3c5a1','5b17e936064db31178a3c5f5','5b17e961064db31178a3c661','5b18e8a6bd6ea136547043ee','5b18e8b8bd6ea13654704421','5b18e8bcbd6ea13654704463'
595 )))
596
597 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 :
598
599 (% class="box" %)
600 (((
601 mongoexport -d step -c reports -q "{'executionID': {'$in': [**'5b17e8fe064db31178a3c5a1','5b17e936064db31178a3c5f5','5b17e961064db31178a3c661','5b18e8a6bd6ea136547043ee','5b18e8b8bd6ea13654704421','5b18e8bcbd6ea13654704463'**]}}" -o reports.csv
602 )))
603
604 This will output to the file "reports.csv" the reports associated with the executions which have ran in the define time window.
605
606 = Restore =
607
608 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.
609
610 == Complete Restore ==
611
612 To fully restore a STEP database from a //backup// folder, use the following command :
613
614 (% class="box" %)
615 (((
616 mongorestore ~-~-drop -d step backup
617 )))
618
619 If you prefer to restore the database from a compressed archive previously created, use the following :
620
621 (% class="box" %)
622 (((
623 mongorestore ~-~-drop -d step ~-~-gzip ~-~-archive=backup.gzip
624 )))
625
626 Warning : using the **~-~-drop** flag will cause the existing content to be deleted ! You should see the following output which confirms the restore succeeded :
627
628 (% class="box" %)
629 (((
630 mongorestore ~-~-drop backup/
631 2017-10-05T10:48:29.070+0000 preparing collections to restore from
632 2017-10-05T10:48:29.089+0000 reading metadata for step.functions from backup/step/functions.metadata.json
633 2017-10-05T10:48:29.098+0000 reading metadata for step.artefacts from backup/step/artefacts.metadata.json
634 2017-10-05T10:48:29.148+0000 reading metadata for step.executions from backup/step/executions.metadata.json
635 2017-10-05T10:48:29.156+0000 reading metadata for step.views from backup/step/views.metadata.json
636 2017-10-05T10:48:29.265+0000 restoring step.functions from backup/step/functions.bson
637 2017-10-05T10:48:29.442+0000 restoring step.artefacts from backup/step/artefacts.bson
638 2017-10-05T10:48:29.584+0000 restoring step.executions from backup/step/executions.bson
639 2017-10-05T10:48:29.719+0000 restoring step.views from backup/step/views.bson
640 2017-10-05T10:48:29.720+0000 no indexes to restore
641 2017-10-05T10:48:29.720+0000 finished restoring step.functions (6 documents)
642 2017-10-05T10:48:29.720+0000 no indexes to restore
643 2017-10-05T10:48:29.720+0000 restoring indexes for collection step.executions from metadata
644 2017-10-05T10:48:29.721+0000 finished restoring step.artefacts (6 documents)
645 2017-10-05T10:48:29.721+0000 restoring indexes for collection step.views from metadata
646 2017-10-05T10:48:29.785+0000 reading metadata for step.reports from backup/step/reports.metadata.json
647 2017-10-05T10:48:30.113+0000 finished restoring step.executions (1 document)
648 2017-10-05T10:48:30.157+0000 reading metadata for step.measurements from backup/step/measurements.metadata.json
649 2017-10-05T10:48:30.255+0000 finished restoring step.views (3 documents)
650 2017-10-05T10:48:30.373+0000 restoring step.reports from backup/step/reports.bson
651 2017-10-05T10:48:30.382+0000 reading metadata for step.users from backup/step/users.metadata.json
652 2017-10-05T10:48:30.498+0000 restoring step.measurements from backup/step/measurements.bson
653 2017-10-05T10:48:30.565+0000 reading metadata for step.controllerlogs from backup/step/controllerlogs.metadata.json
654 2017-10-05T10:48:30.565+0000 restoring indexes for collection step.reports from metadata
655 2017-10-05T10:48:30.699+0000 restoring step.users from backup/step/users.bson
656 2017-10-05T10:48:30.699+0000 restoring indexes for collection step.measurements from metadata
657 2017-10-05T10:48:30.807+0000 restoring step.controllerlogs from backup/step/controllerlogs.bson
658 2017-10-05T10:48:31.235+0000 finished restoring step.reports (3 documents)
659 2017-10-05T10:48:31.316+0000 finished restoring step.measurements (2 documents)
660 2017-10-05T10:48:31.316+0000 no indexes to restore
661 2017-10-05T10:48:31.316+0000 finished restoring step.controllerlogs (1 document)
662 2017-10-05T10:48:31.316+0000 no indexes to restore
663 2017-10-05T10:48:31.316+0000 finished restoring step.users (1 document)
664 2017-10-05T10:48:31.316+0000 done
665 )))
666
667 == Partial restore ==
668
669 To perform a restore of a specific STEP collection, use the following command :
670
671 (% class="box" %)
672 (((
673 mongoimport ~-~-drop -d step -c <collection_name> <collection_name>.json
674 )))
675
676 Warning : using the **~-~-drop** flag will cause the existing collection content to be deleted !
677
678 == Restore your work (Keywords and Test Plans){{id name="work_restore"/}} ==
679
680 You can restore your Keywords and Test Plans from a previous backup using the following commands :
681
682 (% class="box" %)
683 (((
684 mongoimport ~-~-drop -d step -c functions functions.json
685 mongoimport ~-~-drop -d step -c artefacts artefacts.json
686 )))
687
688 = Purge / Maintenance =
689
690 == {{id name="complete_purge"/}}Complete purge ==
691
692 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.
693 Follow below steps :
694
695 * Warning : make sure to [[backup your work first !>>https://github.com/exense/step/releases/latest]]
696 * Connect to you mongo instance and execute the following :
697
698 (% class="box" %)
699 (((
700 ~> use step
701 switched to db step
702 ~> db.dropDatabase();
703 { "dropped" : "step", "ok" : 1 }
704 ~> exit
705 )))
706
707 * [[Restart your controller>>doc:||anchor="controller_restart"]]
708 * [[Restore your Keywords and Test Plans>>doc:||anchor="work_restore"]]
709
710 == Keep only current month results ==
711
712 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.
713
714 * First get the timestamp as **NumberLong** format we will use to perform our queries. Connect to your database and run the following command :
715
716 (% class="box" %)
717 (((
718 ~> NumberLong(ISODate("2017-10-01"))
719 NumberLong("1506816000000") # This is the result we need
720 ~> exit # Exit the database
721 )))
722
723 * We can now export the executions, reports and measurements using following commands :
724
725 (% class="box" %)
726 (((
727 mongoexport -d step -c executions -q '{"startTime":{"$gt":NumberLong("1506816000000")}}' -o executions_gt_20171001.json
728 mongoexport -d step -c measurements -q '{"begin":{"$gt":NumberLong("1506816000000")}}' -o measurements_gt_20171001.json
729 mongoexport -d step -c reports -q '{"executionTime":{"$gt":NumberLong("1506816000000")}}' -o reports_gt_20171001.json
730 )))
731
732 * [[Execute a complete purge>>doc:||anchor="complete_purge"]] (do not forget to re-import your Keyword and Test Plans !)
733 * Restore your last month executions by running following commands :
734
735 (% class="box" %)
736 (((
737 mongoimport -d step -c executions executions_gt_20171001.json
738 mongoimport -d step -c measurements measurements_gt_20171001.json
739 mongoimport -d step -c reports reports_gt_20171001.json
740 )))
741
742 == Export only 1 execution and its data ==
743
744 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 :
745
746 * login to your STEP instance, go to the **Executions** tab and click to the execution you want to get the ID :
747
748 (% style="text-align:center" %)
749 [[image:ExecutionsTab.png||class="img-thumbnail" height="606" width="1500"]]
750
751 * Now that you have the execution ID (in our example it is //59d4d8f9a63eaa00074f6dd0//), you can export the executions and its data :
752
753 {{code}}
754 mongoexport -d step -c executions -q '{"_id":ObjectId("59d4d8f9a63eaa00074f6dd0")}' -o execution_59d4d8f9a63eaa00074f6dd0.json
755 # To export the measurement metrics :
756 mongoexport -d step -c measurements -q '{"eId":"59d4d8f9a63eaa00074f6dd0"}' -o measurements_59d4d8f9a63eaa00074f6dd0.json
757 # To export executions steps :
758 mongoexport -d step -c reports -q '{$or: [ { "parentID":ObjectId("59d4d8f9a63eaa00074f6dd0") }, { "executionID":"59d4d8f9a63eaa00074f6dd0" } ] }' -o reports_59d4d8f9a63eaa00074f6dd0.json
759 {{/code}}
760
761 You can now restore the executions with its associated data using the following :
762
763 {{code}}
764 mongoimport -d step -c executions execution_59d4d8f9a63eaa00074f6dd0.json
765 mongoimport -d step -c measurements measurements_59d4d8f9a63eaa00074f6dd0.json
766 mongoimport -d step -c reports reports_59d4d8f9a63eaa00074f6dd0.json
767 {{/code}}
768
769 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 :
770
771 |=Collections|=Functional results|=Performance metrics
772 |reports|mandatory|mandatory
773 |reports|mandatory(((
774 (% style="text-align:center" %)
775 [[image:Execution.png||height="263" width="750"]]
776 )))|not mandatory
777 |measurements|not mandatory|mandatory(((
778 (% style="text-align:center" %)
779 [[image:Performance.png||height="494" width="750"]]
780 )))
781
782 = Migration =
783
784 Information related to the migration process has been moved to a [[dedicated page >>doc:Versions.3\.9\.x.Migration.WebHome]]in the left menu.
Copyright © exense GmbH
v1.0