-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathgetting_started.html
More file actions
348 lines (294 loc) · 23.4 KB
/
getting_started.html
File metadata and controls
348 lines (294 loc) · 23.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Getting started with Substeps — Substeps documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/theme_extras.js"></script>
<link rel="top" title="Substeps documentation" href="index.html" />
<link rel="next" title="Extending and Customising Substeps" href="extending.html" />
<link rel="prev" title="Usage" href="using.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>Substeps documentation</span></a></h1>
<h2 class="heading"><span>Getting started with Substeps</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="using.html">Usage</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="extending.html">Extending and Customising Substeps</a>  »
</p>
</div>
<div class="content">
<div class="section" id="getting-started-with-substeps">
<h1>Getting started with Substeps<a class="headerlink" href="#getting-started-with-substeps" title="Permalink to this headline">¶</a></h1>
<p>Substeps is not particularly difficult to set up manually, however the quickest route to learning how to use Substeps is to download the sample maven project and then tailor that to your needs. See below on things you will need to configure for your own projects.</p>
<div class="section" id="sample-project">
<h2>Sample project<a class="headerlink" href="#sample-project" title="Permalink to this headline">¶</a></h2>
<p>The sample project can be downloaded from <a class="reference external" href="https://github.com/downloads/technophobia/substeps/example-substeps-project-0.0.1.zip">here</a> which contains all of the required configuration and some sample code to get you started.</p>
</div>
<div class="section" id="manual-setup-maven">
<h2>Manual Setup (Maven)<a class="headerlink" href="#manual-setup-maven" title="Permalink to this headline">¶</a></h2>
<p>These instructions are for building a maven based project.</p>
<ol class="arabic">
<li><p class="first">Create an ‘acceptance-test’ project.</p>
</li>
<li><p class="first">Include the substeps dependencies</p>
<blockquote>
<div><p>If you wish to run acceptance tests against a web application using selenium webdriver:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><dependency></span>
<span class="nt"><groupId></span>com.technophobia.substeps<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>webdriver-substeps<span class="nt"></artifactId></span>
<span class="nt"><version></span>0.0.3<span class="nt"></version></span>
<span class="nt"></dependency></span>
</pre></div>
</div>
<p>The above dependency will also include substeps-core, however if you wish to create your own or use other step implementations then include</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><dependency></span>
<span class="nt"><groupId></span>com.technophobia.substeps<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>substeps-core<span class="nt"></artifactId></span>
<span class="nt"><version></span>0.0.5<span class="nt"></version></span>
<span class="nt"></dependency></span>
</pre></div>
</div>
<p>Check <a class="reference external" href="http://search.maven.org/#search|ga|1|com.technophobia.substeps">Maven Central</a> for the latest versions of these libraries.</p>
</div></blockquote>
</li>
<li><p class="first">Create a directory on the classpath to contain your feature files or sub-directories of feature files (eg <tt class="docutils literal"><span class="pre">src/test/resources/features</span></tt>).</p>
</li>
<li><p class="first">Create a directory on the classpath to contain substep files (eg <tt class="docutils literal"><span class="pre">src/test/resources/substeps</span></tt>).</p>
</li>
<li><p class="first">Create a junit class to run the tests in ‘development’ mode:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="nd">@SubStepsConfiguration</span><span class="o">(</span><span class="n">featureFile</span> <span class="o">=</span> <span class="s">"./target/test-classes/features"</span><span class="o">,</span>
<span class="n">subStepsFile</span> <span class="o">=</span> <span class="s">"./target/test-classes/substeps"</span><span class="o">,</span>
<span class="n">stepImplementations</span> <span class="o">=</span> <span class="o">{</span><span class="n">BaseWebdriverSubStepImplementations</span><span class="o">.</span><span class="na">class</span> <span class="o">},</span>
<span class="n">beforeAndAfterImplementations</span> <span class="o">={</span><span class="n">DefaultExecutionSetupTearDown</span><span class="o">.</span><span class="na">class</span><span class="o">})</span>
<span class="nd">@RunWith</span><span class="o">(</span><span class="n">JunitFeatureRunner</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">AcceptanceTestsRunner</span> <span class="o">{</span>
<span class="c1">// no op</span>
<span class="o">}</span>
</pre></div>
</div>
<p>If you have bespoke step implementations then add to the list of step implementations above,
likewise if you have specific setup and tear down functionality add this to the
<tt class="docutils literal"><span class="pre">beforeAndAfterImplementations</span></tt> parameter.
Setup and tear down methods will need to have the appropriate annotation, eg <tt class="docutils literal"><span class="pre">@BeforeAllFeatures</span></tt> etc
to signify when in the lifecycle to call that method.
See the javadoc for com.technophobia.substeps.runner.setupteardown.Annotations for more details.</p>
<p>Additional properties can also be specified see <junitFeatureRunner details> for more details</p>
</li>
<li><p class="first">create a configuration file <tt class="docutils literal"><span class="pre">localhost.properties</span></tt> and place in the classpath (<tt class="docutils literal"><span class="pre">src/test/resources</span></tt>).
This property file will contain all of the environment settings for substeps.
Substep libraries might each include their own set of default properties,
the values in this file will override the defaults.</p>
</li>
<li><p class="first">To run the tests:
Simply run the class as a Junit test; in Eclipse select the ‘AcceptanceTestsRunner’ class, right click
and select Run As, junit test.</p>
</li>
<li><p class="first">Continuous integration (using Maven)</p>
<p>The substeps maven plugin can execute a number of configurations as part of an integration test.
Each configuration can be tailored to use specific properties, sets of tests or alternate
initialisation classes and or step implementations. The plugin adds all the dependencies of the project
to it’s own set of dependencies to avoid duplication in the pom.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><plugin></span>
<span class="nt"><groupId></span>com.technophobia.substeps<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>substeps-runner<span class="nt"></artifactId></span>
<span class="nt"><version></span>0.0.4<span class="nt"></version></span>
<span class="nt"><executions></span>
<span class="nt"><execution></span>
<span class="nt"><id></span>SubSteps Test<span class="nt"></id></span>
<span class="nt"><phase></span>integration-test<span class="nt"></phase></span>
<span class="nt"><goals></span>
<span class="nt"><goal></span>run-features<span class="nt"></goal></span>
<span class="nt"></goals></span>
<span class="nt"></execution></span>
<span class="nt"></executions></span>
<span class="nt"><configuration></span>
...
</pre></div>
</div>
<p>See #Substeps Maven Plugin for full details of the parameters and options available.</p>
</li>
<li><p class="first">An Example pom</p>
<p>This example pom is taken from the sample project, feel free to copy and adapt.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><project</span> <span class="na">xmlns=</span><span class="s">"http://maven.apache.org/POM/4.0.0"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
<span class="na">xsi:schemaLocation=</span><span class="s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"</span><span class="nt">></span>
<span class="nt"><modelVersion></span>4.0.0<span class="nt"></modelVersion></span>
<span class="c"><!-- This is a sample pom configuration for building a suite of substep</span>
<span class="c"> acceptance tests based on the webdriver step implementations --></span>
<span class="c"><!-- Change these values to something appropriate for your organisation</span>
<span class="c"> and project --></span>
<span class="nt"><groupId></span>com.technophobia.substeps<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>webdriver-substeps-example<span class="nt"></artifactId></span>
<span class="nt"><version></span>0.0.1-SNAPSHOT<span class="nt"></version></span>
<span class="nt"><packaging></span>jar<span class="nt"></packaging></span>
<span class="nt"><name></span>Webdriver Substeps Example<span class="nt"></name></span>
<span class="nt"><description></span>An example webdriver substeps project<span class="nt"></description></span>
<span class="nt"><licenses></span>
<span class="nt"><license></span>
<span class="nt"><name></span>LGPL 3.0 license<span class="nt"></name></span>
<span class="nt"><url></span>http://www.opensource.org/licenses/lgpl-3.0.html<span class="nt"></url></span>
<span class="nt"><distribution></span>manual<span class="nt"></distribution></span>
<span class="nt"></license></span>
<span class="nt"></licenses></span>
<span class="nt"><properties></span>
<span class="nt"><project.build.sourceEncoding></span>UTF-8<span class="nt"></project.build.sourceEncoding></span>
<span class="nt"><project.reporting.outputEncoding></span>UTF-8<span class="nt"></project.reporting.outputEncoding></span>
<span class="nt"><selenium.version></span>2.21.0<span class="nt"></selenium.version></span>
<span class="nt"><hamcrest.version></span>1.3.RC2<span class="nt"></hamcrest.version></span>
<span class="nt"><junit.version></span>4.10<span class="nt"></junit.version></span>
<span class="nt"><substeps.runner.version></span>0.0.4<span class="nt"></substeps.runner.version></span>
<span class="nt"><webdriver.substeps.version></span>0.0.3<span class="nt"></webdriver.substeps.version></span>
<span class="nt"></properties></span>
<span class="nt"><dependencies></span>
<span class="c"><!-- webdriver-substeps will also include substeps-core as a dependency --></span>
<span class="nt"><dependency></span>
<span class="nt"><groupId></span>com.technophobia.substeps<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>webdriver-substeps<span class="nt"></artifactId></span>
<span class="nt"><version></span>${webdriver.substeps.version}<span class="nt"></version></span>
<span class="nt"></dependency></span>
<span class="nt"><dependency></span>
<span class="nt"><groupId></span>org.seleniumhq.selenium<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>selenium-java<span class="nt"></artifactId></span>
<span class="nt"><version></span>${selenium.version}<span class="nt"></version></span>
<span class="nt"></dependency></span>
<span class="nt"></dependencies></span>
<span class="nt"><profiles></span>
<span class="c"><!-- In this example, the running of the acceptance tests is defined within</span>
<span class="c"> a profile, during the integration-test phase of the maven build.</span>
<span class="c"> See the substeps-runner documentation for more details. --></span>
<span class="nt"><profile></span>
<span class="nt"><id></span>acceptance-tests<span class="nt"></id></span>
<span class="nt"><activation></span>
<span class="nt"><activeByDefault></span>true<span class="nt"></activeByDefault></span>
<span class="nt"></activation></span>
<span class="nt"><build></span>
<span class="nt"><plugins></span>
<span class="nt"><plugin></span>
<span class="nt"><groupId></span>com.technophobia.substeps<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>substeps-runner<span class="nt"></artifactId></span>
<span class="nt"><version></span>${substeps.runner.version}<span class="nt"></version></span>
<span class="nt"><executions></span>
<span class="nt"><execution></span>
<span class="nt"><id></span>SubSteps Test<span class="nt"></id></span>
<span class="nt"><phase></span>integration-test<span class="nt"></phase></span>
<span class="nt"><goals></span>
<span class="nt"><goal></span>run-features<span class="nt"></goal></span>
<span class="nt"></goals></span>
<span class="nt"></execution></span>
<span class="nt"></executions></span>
<span class="nt"><configuration></span>
<span class="nt"><executionConfigs></span>
<span class="c"><!-- One or more 'execution configurations', use multiple configs for different</span>
<span class="c"> test initialisation, phases of project, etc --></span>
<span class="nt"><executionConfig></span>
<span class="c"><!-- This appears at the root of the results report --></span>
<span class="nt"><description></span>Self Test Features<span class="nt"></description></span>
<span class="c"><!-- optional - If the feature or scenario has this tag, then it will be</span>
<span class="c"> included, otherwise it won't --></span>
<span class="nt"><tags></span>@all<span class="nt"></tags></span>
<span class="c"><!-- optional - if true any parse errors will fail the build immediately,</span>
<span class="c"> rather than attempting to execute as much as possible and fail those tests</span>
<span class="c"> that can't be parsed --></span>
<span class="nt"><fastFailParseErrors></span>false<span class="nt"></fastFailParseErrors></span>
<span class="c"><!-- path to the feature file, or directory containing the feature files --></span>
<span class="nt"><featureFile></span>${basedir}/target/test-classes/features<span class="nt"></featureFile></span>
<span class="c"><!-- path to directory of substep files, or a single substep file --></span>
<span class="nt"><subStepsFileName></span>${basedir}/target/test-classes/substeps<span class="nt"></subStepsFileName></span>
<span class="c"><!-- List of classes containing step implementations --></span>
<span class="nt"><stepImplementationClassNames></span>
<span class="nt"><param></span>com.technophobia.webdriver.substeps.impl.BaseWebdriverSubStepImplementations<span class="nt"></param></span>
<span class="nt"><param></span>com.technophobia.webdriver.substeps.example.ExampleCustomWebdriverStepImplementations<span class="nt"></param></span>
<span class="nt"></stepImplementationClassNames></span>
<span class="c"><!-- Ordered list of classes containing setup and tear down methods --></span>
<span class="nt"><initialisationClass></span>
<span class="nt"><param></span>com.technophobia.webdriver.substeps.runner.DefaultExecutionSetupTearDown<span class="nt"></param></span>
<span class="nt"><param></span>com.technophobia.webdriver.substeps.example.ExampleSetupAndTearDown<span class="nt"></param></span>
<span class="nt"></initialisationClass></span>
<span class="nt"></executionConfig></span>
<span class="nt"></executionConfigs></span>
<span class="c"><!-- Default HTML report builder --></span>
<span class="nt"><executionReportBuilder</span>
<span class="na">implementation=</span><span class="s">"com.technophobia.substeps.report.DefaultExecutionReportBuilder"</span><span class="nt">></span>
<span class="c"><!-- The directory in which the test execution report will be written</span>
<span class="c"> to --></span>
<span class="nt"><outputDirectory></span>${project.build.testOutputDirectory}<span class="nt"></outputDirectory></span>
<span class="nt"></executionReportBuilder></span>
<span class="nt"></configuration></span>
<span class="nt"><dependencies></span>
<span class="c"><!-- NB. The plugin uses all test dependencies defined in this project,</span>
<span class="c"> as it's own so there is no need to list separately. The exception is an slf4j</span>
<span class="c"> logging implementation, which is required before other dependencies have</span>
<span class="c"> been added. This logger is included as an example, it can be replaced with</span>
<span class="c"> another slf4j logger of your choice. --></span>
<span class="nt"><dependency></span>
<span class="nt"><groupId></span>org.slf4j<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>slf4j-log4j12<span class="nt"></artifactId></span>
<span class="nt"><version></span>1.6.4<span class="nt"></version></span>
<span class="nt"></dependency></span>
<span class="nt"></dependencies></span>
<span class="nt"></plugin></span>
<span class="nt"></plugins></span>
<span class="nt"></build></span>
<span class="nt"></profile></span>
<span class="nt"></profiles></span>
<span class="c"><!-- this section may be unnecessary depending on your maven configuration --></span>
<span class="nt"><build></span>
<span class="nt"><finalName></span>${project.artifactId}<span class="nt"></finalName></span>
<span class="nt"><plugins></span>
<span class="nt"><plugin></span>
<span class="nt"><groupId></span>org.apache.maven.plugins<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>maven-compiler-plugin<span class="nt"></artifactId></span>
<span class="nt"><configuration></span>
<span class="nt"><source></span>1.5<span class="nt"></source></span>
<span class="nt"><target></span>1.5<span class="nt"></target></span>
<span class="nt"><inherit></span>true<span class="nt"></inherit></span>
<span class="nt"><encoding></span>${project.build.sourceEncoding}<span class="nt"></encoding></span>
<span class="nt"></configuration></span>
<span class="nt"></plugin></span>
<span class="nt"></plugins></span>
<span class="nt"></build></span>
<span class="nt"></project></span>
</pre></div>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="using.html">Usage</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="extending.html">Extending and Customising Substeps</a>  »
</p>
</div>
<div class="footer">
© Copyright 2012, Technophobia.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>