Skip to main content
summaryrefslogtreecommitdiffstats
blob: 5250c2f3ac190d4f84d1fdd14ccbf8678dda5b19 (plain) (blame)
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
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
<?xml version="1.0" encoding="UTF-8"?>
<!--
    Copyright (c) 2015 BREDEX GmbH.
    All rights reserved. This program and the accompanying materials
    are made available under the terms of the Eclipse Public License v1.0
    which accompanies this distribution, and is available at
    http://www.eclipse.org/legal/epl-v10.html
 -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xl="http://www.w3.org/1999/xlink" xml:id="clientAPI" version="5.0">
 <?dbhtml dir="clientAPI"?>
    <title>Writing UI tests via client API</title>
    <section>
        <title>The general idea</title>
        <figure xml:id="api-idea">
            <title>Idea behind the API</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/api-idea.png" />
                </imageobject>
            </mediaobject>
        </figure>
        <para>
            The main idea behind Jubula's client API is to allow the execution of
            Test Steps (CAPs) from within arbitrary Java code e.g. JUnit test cases
            (see <xref linkend="api-idea" />). At the same time of shifting the paradigm to target a developer
            audience we've tried to stick to our principles:
        </para>
        <itemizedlist>
            <listitem>
                <para>offer high-level test steps that are equivalent to the ones
                    available in the ITE: all test steps that are being executed via
                    the API behave 1:1 the same as the ones executed by the ITE.
                </para>
            </listitem>
            <listitem>
                <para>an API for all toolkits: the client API is available for all
                    toolkits supported by the ITE like JavaFX, AWT/Swing,
                    SWT/RCP/GEF, HTML.
                </para>
            </listitem>
            <listitem>
                <para>
                    offer toolkit abstraction layer to keep your tests UI toolkit
                    independent: the usage of the API will also allow you to specify
                    your tests in a toolkit neutral way. Please note that for all of
                    the concrete toolkit wrapper types abstracted super types are
                    provided e.g. to address a
                    <emphasis>javafx.scene.control.CheckBox</emphasis>
                    we provide the wrapper type containing its test steps
                    <emphasis>org.eclipse.jubula.toolkit.javafx.components.CheckBox
                    </emphasis>
                    but the underlying abstracted toolkit conceptual component is
                    <emphasis>org.eclipse.jubula.toolkit.concrete.components.ButtonComponent
                    </emphasis>
                    .
                </para>
            </listitem>
            <listitem>
                <para>de-couple tests and real UI widgets: you still have to create
                    an object mapping (via the ITE and export it) to keep the
                    information that are required to determine which widget to address
                    during runtime independent from your test specification.
                </para>
            </listitem>
            <listitem>
                <para>separation of test and AUT runtime environments: the JVM
                    executing the tests is a separate one (and may also e.g. run on
                    a different machine) from the one the AUT gets executed in. It's
                    communicating with the AUT VM via a TCP/IP connection.
                </para>
            </listitem>
            <listitem>
                <para>the AUT-Agent manages the lifecycle of AUTs: starting /
                    stopping / restarting of AUTs is still done by instructing the
                    AUT-Agent to do so and may also be extended by the usage of
                    autrun to launch applications externally.
                </para>
            </listitem>
        </itemizedlist>
    </section>
    
    <section>
        <title>General steps to take and class overview</title>
        <figure xml:id="api-classes">
            <title>The most important classes and their methods</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/api-classes.png" />
                </imageobject>
            </mediaobject>
        </figure>
        <para> Taking this as a basis, a normal execution of test steps via the
            client API requires - in general - the following steps:
        </para>
        <orderedlist>
            <listitem>
                <para>Connect to an already running instance of the AUT-Agent.
                </para>
            </listitem>
            <listitem>
                <para>Instruct it to start an AUT or retrieve a list of all
                    currently known AUT identifier.
                </para>
            </listitem>
            <listitem>
                <para>Connect to the AUT by using the AUT identifier.
                </para>
            </listitem>
            <listitem>
                <para>
                    Execute an arbitrary amount of CAPs (<emphasis role="strong">C</emphasis>omponent
                    <emphasis role="strong">A</emphasis>ction
                    <emphasis role="strong">P</emphasis>arameter also known as Test steps) on this established
                    connection to an AUT. Note: there is no result
                    processing implemented.
                </para>
            </listitem>
            <listitem>
                <para>Disconnect from the AUT.
                </para>
            </listitem>
            <listitem>
                <para>Stop the AUT.
                </para>
            </listitem>
            <listitem>
                <para>Disconnect from the AUT-Agent.
                </para>
            </listitem>
        </orderedlist>
        <para>
            <xref linkend="api-classes" />
            allows to get a general overview of the toolkit neutral parts of the
            client API.
        </para>
    </section>

    <section>
        <title>Exporting the Object Map in the ITE</title>
        <figure xml:id="export-om">
            <title>Object Mapping Editor export function</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/export-om.png" />
                </imageobject>
            </mediaobject>
        </figure>
        <para>
            In order to create an executable CAP instance (see <xref linkend="creating-cap-instances" />) you require a valid
            <emphasis>org.eclipse.jubula.tools.ComponentIdentifier</emphasis> instance. To get that, you need to
        </para>
        <orderedlist>
            <listitem>
                <para>Start the ITE, open the project and the Object Mapping Editor for the AUT you wan't to export the Object Map for. (Or, if you are starting from scratch, firstly create a new project and do the object mapping there.)
                </para>
            </listitem>
            <listitem>
                <para>Select technical names or categories you want to export(or none if you want to export all) and choose "Export Object Mapping for use in API" from the context menu of the editor as shown in <xref linkend="export-om" />.
                </para>
            </listitem>
            <listitem>
                <para>Decide whether you wan't to use a plain properties file or a Java class with static fields. 
                Both formats will then contain all necessary information (one mapping for each mapped logical component name) to address the UI widget when the test gets executed. 
                </para>
            </listitem>
            <listitem>
                <para>Place this resource on the classpath of your test project. 
                </para>
            </listitem>
            <listitem>
                <para>If you're using the properties file format you can load the mapping and its identifier by using <emphasis>MakeR.createObjectMapping(...).get("logicalComponentName")</emphasis>.
                Otherwise you can simply access the static fields of the exported class.
                </para>
            </listitem>
        </orderedlist>
        <para>You can also get an encoded ComponentIdentifier directly to the clipboard. This is useful if you want to replace an existing ComponentIdentifier in the API. Simply select the technical name and choose "Copy Component Identifier to clipboard" from the context menu of the editor.</para> 
        <para role="warning">Currently the structure and information used to address a component (the mapping value itself) is not part of the API itself. Hence you still have to maintain this information within the ITE. 
        </para>
    </section>
    
    <section xml:id="creating-cap-instances">
        <title>Creating CAP instances</title>
        <figure xml:id="toolkit-factories">
            <title>JavaFX-Toolkit component factory usage to create an instance for a CheckBox</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/tk-factories.png" />
                </imageobject>
            </mediaobject>
        </figure>
        <para>In order to create executable instances of a <emphasis>org.eclipse.jubula.communication.CAP</emphasis> (Test Step) you have to use the corresponding 
        factory methods available for each toolkit and pass a valid and fitting ComponentIdentifier:</para>
        <itemizedlist>
            <listitem>
                <para>org.eclipse.jubula.toolkit.javafx.JavafxComponents - see e.g. the <xref linkend="toolkit-factories" /></para>
            </listitem>
            <listitem>
                <para>org.eclipse.jubula.toolkit.swing.SwingComponents</para>
            </listitem>
            <listitem>
                <para>org.eclipse.jubula.toolkit.html.HtmlComponents</para>
            </listitem>
            <listitem>
                <para>org.eclipse.jubula.toolkit.swt.SwtComponents</para>
            </listitem>
        </itemizedlist>
        <para>On these UI component placeholder instances you can call methods that will return 
        an executable CAP that, when being executed on the AUT connection, 
        performs the specified test step:</para>
        <figure xml:id="cap-factory-methods">
            <title>Creating a CAP instance</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/cap-factory-methods.png" />
                </imageobject>
            </mediaobject>
        </figure>
    </section>
    
    <section>
        <title>General setup information</title>
        <para>The following section describes where to find the relevant JARs / artifacts to use the API.
        The provided API has a miminum required runtime environment of <emphasis role="strong">Java 6</emphasis>.</para>
        <para>In general the usage of the client API falls apart into three categories of JARs / maven artifacts 
        / OSGi bundles:</para>
        <orderedlist>
            <listitem>
                <para>Each project requires dependencies to <emphasis role="strong">all</emphasis> of the <emphasis role="strong">toolkit neutral parts</emphasis>
                of the API:</para>
                <itemizedlist>
                    <listitem>
                        <para>org.eclipse.jubula.client.api</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.client.api.commands</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.toolkit.api</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.tools</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.communication</para>
                    </listitem>
                </itemizedlist>
            </listitem>
            <listitem>
                <para>Each project requires dependencies to <emphasis role="strong">indiviual</emphasis> parts of the <emphasis role="strong">toolkit specific elements</emphasis>
                dependent from the used toolkit of the API:</para>
                <itemizedlist>
                    <listitem>
                        <para>org.eclipse.jubula.toolkit.base.api</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.toolkit.concrete.api</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.toolkit.javafx.api</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.toolkit.swt.api</para>
                    </listitem>
                    <listitem>
                        <para>org.eclipse.jubula.toolkit...TOOLKIT_ID...api</para>
                    </listitem>
                </itemizedlist>
                <para>Please keep in mind that <emphasis role="strong">toolkits are derived</emphasis> from each other. So if you're e.g. setting up a JavaFX projects it is also 
                necessary to include the direct dependency to the specific toolkit artifact "org.eclipse.jubula.toolkit.javafx.api" itself as well as the toolkits its based upon: 
                "org.eclipse.jubula.toolkit.concrete.api" and its base "org.eclipse.jubula.toolkit.base.api".</para>
            </listitem>
            <listitem>
                <para>Each project also requires dependencies to <emphasis role="strong">all</emphasis> of the <emphasis role="strong">3rd party dependencies</emphasis>
                of the API:</para>
                <itemizedlist>
                    <listitem>
                        <para>Apache Commons Lang 2.6</para>
                    </listitem>
                    <listitem>
                        <para>Apache Commons Codec 1.6</para>
                    </listitem>
                    <listitem>
                        <para>SLF4j API</para>
                    </listitem>
                    <listitem>
                        <para>XStream 1.3.1</para>
                    </listitem>
                    <listitem>
                        <para>xmlpull 1.1.3.4a</para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </orderedlist>
        <para>You can find the artifacts in different shapes (plain JAR and maven artifact) within
        the <emphasis>&lt;ITEInstallationFolder&gt;/development/api</emphasis> folder. To define OSGi dependencies to the API artifacts
        you can simply include the <emphasis>&lt;ITEInstallationFolder&gt;/development/org.eclipse.jubula.repo.zip</emphasis> in
        your target platform (definition) and define a dependency to the "Jubula Functional Testing - API Core"-feature.</para>
        <para>A list of changes which happened over time in the API is located <link xl:href="../../api-comparison/index.html">here</link>.</para>
    </section>
    
    <section>
        <title>Sample setup of the API usage</title>
        <figure xml:id="start-aut">
            <title>Starting the RCP-SimpleAdder AUT via API</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/start-aut.png" />
                </imageobject>
            </mediaobject>
        </figure>
        <para>A fully executable example setup for the RCP toolkit showing a basic SimpleAdder AUT start - see <xref linkend="start-aut" /> - 
        and test run - see <xref linkend="test-execution" /> - can be found in the git-Repository contained within every ITE installation. It's located in 
        <emphasis>&lt;ITEInstallationFolder&gt;/development/git/org.eclipse.jubula.core.git</emphasis>. Simply create a clone
        of that repository and checkout the Eclipse projects <emphasis>org.eclipse.jubula.examples.api.adder.rcp.*</emphasis>.
        There is an individual preconfigured project for all of the three shapes the API may be consumed as:</para>
        <itemizedlist>
            <listitem>
            <para>
                <emphasis role="strong">plain JAR:</emphasis>
                The project for this example setup is
                <emphasis>org.eclipse.jubula.examples.api.adder.rcp.jar
                </emphasis>
                . You still have to adjust the path to the (by default linked to
                relative / local artifacts located within the git-clone itself)
                library-directory (lib). Simply adjust this path to point to
                e.g.
                <emphasis>&lt;ITEInstallationFolder&gt;/development/api/JARs/</emphasis>
                .
            </para>
            </listitem>
            <listitem>
            <para>
                <emphasis role="strong">m2 / maven:</emphasis>
                The project for this example setup is
                <emphasis>org.eclipse.jubula.examples.api.adder.rcp.m2
                </emphasis>
                . You still have to adjust the path to the local maven
                repository within the pom.xml of that project and point to the
                one included in the installation:
                <emphasis>&lt;ITEInstallationFolder&gt;/development/api/m2-repo
                </emphasis>
                .
            </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis role="strong">OSGi:</emphasis>
                    The project for this example setup is
                    <emphasis>org.eclipse.jubula.examples.api.adder.rcp.osgi
                    </emphasis>
                    . You still have to add the (e.g. local) Jubula p2-repository and its
                    artifacts to your target platform:
                    <emphasis>&lt;ITEInstallationFolder&gt;/development/org.eclipse.jubula.repo.zip
                    </emphasis>
                </para>
            </listitem>
        </itemizedlist>
        <figure xml:id="test-execution">
            <title>Executing a first test</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/test-execution.png" />
                </imageobject>
            </mediaobject>
        </figure>
    </section>
    
    <section>
        <title>Working with Actionhandlers</title>
        <para>Actionhandlers are a way to execute actions without creating a CAP
            manually first, they create and validate the CAP internally
            when a method is called.</para>
        <para>
            The idea behind using Actionhandlers is to easier modularize tests.
            If a parameter of a method is null the action will not be executed,
            you can therefore create modules where not all actions are executed if the
            data for them is null.
            This allows to cover a wide range of potential tests with a single method call.
        </para>
        <para>
            The general setup for API usage is the same as in the previous section.
            However beign able to execute a test we need to first register the AUT
            at the AUTRegistry, otherwise upon executing a test an Exception will occur.
        </para>
        <figure xml:id="actionhandler-test-execution">
            <title>Executing a test using an Actionhandler</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/actionhandler-test.png" />
                </imageobject>
            </mediaobject>
        </figure>
    </section>
    <xi:include href="sectionEmbeddedAgent.xml"/>
    <xi:include href="sectionConverter.xml"/>
</chapter>

Back to the top