-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathextending.html
192 lines (174 loc) · 12.4 KB
/
extending.html
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
<!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>Extending and Customising 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="Related Projects" href="related_projects.html" />
<link rel="prev" title="Getting started with Substeps" href="getting_started.html" />
</head>
<body>
<div class="header"><h1 class="heading"><a href="index.html">
<span>Substeps documentation</span></a></h1>
<h2 class="heading"><span>Extending and Customising Substeps</span></h2>
</div>
<div class="topnav">
<p>
«  <a href="getting_started.html">Getting started with Substeps</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="related_projects.html">Related Projects</a>  »
</p>
</div>
<div class="content">
<div class="section" id="extending-and-customising-substeps">
<h1><a class="toc-backref" href="#id1">Extending and Customising Substeps</a><a class="headerlink" href="#extending-and-customising-substeps" title="Permalink to this headline">¶</a></h1>
<p>Substeps is designed to be extensible, many projects are subtly different and the step implementations
required to test the application also have to vary. Substeps can easily be extended or customised using new step implementations,
either as simple classes, or packaged inside a jar as a library.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This section is aimed at developers, implementing new steps or libraries of step implementations.</p>
</div>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#extending-and-customising-substeps" id="id1">Extending and Customising Substeps</a><ul>
<li><a class="reference internal" href="#step-implementations" id="id2">Step Implementations</a></li>
<li><a class="reference internal" href="#context" id="id3">Context</a></li>
<li><a class="reference internal" href="#properties" id="id4">Properties</a></li>
<li><a class="reference internal" href="#documentation" id="id5">Documentation</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="step-implementations">
<h2><a class="toc-backref" href="#id2">Step Implementations</a><a class="headerlink" href="#step-implementations" title="Permalink to this headline">¶</a></h2>
<p>Custom step implementations can be implemented by annotating a class with <tt class="docutils literal"><span class="pre">@StepImplementations</span></tt> and
including the class in the run configurations described above.
Each step implemenation method should be annotated with <tt class="docutils literal"><span class="pre">@Step("<expression>")</span></tt> where <expression>
is a java regular expression that is used to match on the strings from feature and substep files.
Capture groups can be used to map to parameters eg:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="nd">@Step</span><span class="o">(</span><span class="s">"DoSomething name=\"([^\"]*)\", value=\"([^\"]*)\""</span><span class="o">)</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">doSomething</span><span class="o">(</span><span class="kd">final</span> <span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">value</span><span class="o">){</span>
<span class="o">...</span>
</pre></div>
</div>
<p>Parameters can be converted to other simple types using the @StepParameter annotation and
an appropriate Converter, eg:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="nd">@Step</span><span class="o">(</span><span class="s">"DoSomethingElse checked=\"([^\"]*)\""</span><span class="o">)</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">doSomethingElse</span><span class="o">(</span> <span class="nd">@StepParameter</span><span class="o">(</span><span class="n">converter</span> <span class="o">=</span> <span class="n">BooleanConverter</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> <span class="kd">final</span> <span class="n">Boolean</span> <span class="n">checked</span><span class="o">)</span> <span class="o">{</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The actual implementation can do whatever is necessary, if you need to use functionality from
other StepImplementations classes or methods, it is possible to simply instantiate the class
and call directly.</p>
</div>
<div class="section" id="context">
<h2><a class="toc-backref" href="#id3">Context</a><a class="headerlink" href="#context" title="Permalink to this headline">¶</a></h2>
<p>An ExecutionContext is maintained throughout the testing cycle, bound to the current Thread.
This allows data to be placed into a scoped context for subsequent use, scopes include suite,
feature, scenario, etc. See Scope javadocs for more details. At the end of the scope, the
framework will remove the objects in that scope. This functionality is useful for passing
data between steps for example, eg one step checks that a particular function worked and
returned a value, a subsequent step can then use that value.
See ExecutionContext javadocs for more details</p>
<p>Usage:</p>
<div class="highlight-java"><pre>ExecutionContext.put(Scope.SCENARIO, “new_user_id”, user_id);
Object object = ExecutionContext.get(Scope.SCENARIO, “new_user_id”);</pre>
</div>
</div>
<div class="section" id="properties">
<h2><a class="toc-backref" href="#id4">Properties</a><a class="headerlink" href="#properties" title="Permalink to this headline">¶</a></h2>
<p>It is possible a new library of substep implementations will need to make use of various
environment specific properties. To avoid a profusion of properties files that need to be
maintained for each environment and substeps libraries, a single mechanism is used.
By default localhost.properties is used, however this can be overriden by
specifying -Denvironment=test_server for example to use test_server.properties instead.</p>
<p>If you are creating a new substep implementation library and require new configuration,
create an enum to hold your configuration values and initialise in a static initialiser:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kd">enum</span> <span class="n">MyNewConfiguration</span><span class="o">{</span>
<span class="kd">private</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">int</span> <span class="n">MAX_COUNT</span><span class="o">;</span>
<span class="o">...</span>
<span class="kd">static</span> <span class="o">{</span>
<span class="kd">final</span> <span class="n">URL</span> <span class="n">defaultURL</span> <span class="o">=</span> <span class="n">MyNewConfiguration</span><span class="o">.</span><span class="na">class</span><span class="o">.</span><span class="na">getResource</span><span class="o">(</span><span class="s">"/default-my-new-substeps-library.properties"</span><span class="o">);</span>
<span class="n">Assert</span><span class="o">.</span><span class="na">assertNotNull</span><span class="o">(</span><span class="n">defaultURL</span><span class="o">);</span>
<span class="n">Configuration</span><span class="o">.</span><span class="na">INSTANCE</span><span class="o">.</span><span class="na">addDefaultProperties</span><span class="o">(</span><span class="n">defaultURL</span><span class="o">,</span> <span class="s">"default-my-new-substeps-library"</span><span class="o">);</span>
<span class="n">MAX_COUNT</span> <span class="o">=</span> <span class="n">Configuration</span><span class="o">.</span><span class="na">INSTANCE</span><span class="o">.</span><span class="na">getInt</span><span class="o">(</span><span class="s">"new.library.max.count"</span><span class="o">);</span>
<span class="o">...</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Default values can be provided in the specified properties file packaged with the
library and overridden in the same substeps property file used for other settings.</p>
</div>
<div class="section" id="documentation">
<h2><a class="toc-backref" href="#id5">Documentation</a><a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2>
<p>A fundamental part of writing new step implementations is the documentation that
provides understanding to users of the new implementations, without understanding, usage might
not be as efficient or correct as you, the implementor would like. The substeps framework
provides some help in this area, simply use the following annotations within the javadoc
for the method eg.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="cm">/**</span>
<span class="cm"> * Asserts a value of a radio button</span>
<span class="cm"> *</span>
<span class="cm"> * @example AssertRadioButton name="radio_btn_name", text="text",</span>
<span class="cm"> * checked="true"</span>
<span class="cm"> * @section Forms</span>
<span class="cm"> * @param name</span>
<span class="cm"> * the name</span>
<span class="cm"> * @param text</span>
<span class="cm"> * text value</span>
<span class="cm"> * @param checked</span>
<span class="cm"> * true or false to indicate wether the checkbox is checked or</span>
<span class="cm"> * not</span>
<span class="cm"> */</span>
<span class="nd">@Step</span><span class="o">(</span><span class="s">"AssertRadioButton name=\"([^\"]*)\", text=\"([^\"]*)\", checked=\"([^\"]*)\""</span><span class="o">)</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="n">assertRadioButton</span> <span class="o">....</span>
</pre></div>
</div>
<p>The custom javadoc tags <tt class="docutils literal"><span class="pre">@example</span></tt>, <tt class="docutils literal"><span class="pre">@section</span></tt>, along with the standard description and parameter names
are parsed by a bespoke javadoc doclet and can be extracted for
publishing in a wiki or within the context sensitive help of the eclipse plugin.</p>
<p>see substep implementation publisher</p>
<p>If you are writing a set of step implementations that you wish to distribute, then
it’s a good idea to include the susbteps-meta-inf.xml in the jar file that you distribute.
This will enable the ecplipse plugin and maven publisher plugins to have access to the
custom javadoc annotations and parameter names, which in turn will help users of your library.</p>
</div>
</div>
</div>
<div class="bottomnav">
<p>
«  <a href="getting_started.html">Getting started with Substeps</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="related_projects.html">Related Projects</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>