blob: c75c64cff032d56f93b5adfe763f7a975e2ee4b8 [file] [log] [blame]
<!DOCTYPE html>
<head>
<title>RCPTT Documentation Center</title>
<meta charset="UTF-8">
<link rel="stylesheet" href="https://www.eclipse.org/rcptt/shared/css/bootstrap.min.css">
<link rel="stylesheet" href="https://www.eclipse.org/rcptt/shared/css/main.css">
<link rel="stylesheet" href="https://www.eclipse.org/rcptt/shared/css/prism.css">
<link rel="icon" href="https://www.eclipse.org/rcptt/shared/img/favicon.ico">
<script src="https://www.eclipse.org/rcptt/shared/js/jquery.min.js"></script>
<script src="https://www.eclipse.org/rcptt/shared/js/bootstrap.min.js"></script>
<script src="https://www.eclipse.org/rcptt/shared/js/prism.js"></script>
<script src="https://www.eclipse.org/rcptt/shared/js/ecl.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-39589807-5', 'eclipse.org');
ga('send', 'pageview');
</script>
</head>
<body>
<div id="before-footer">
<header>
<nav class="navbar navbar-default navbar-static-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">RCPTT Documentation Center</span>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav">
<li class="active" >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/getstarted">User Guide</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/faq/">FAQ</a>
</li>
<li>
<a href="http://eclipse.org/rcptt">Back to RCPTT Main Site</a>
</li>
<li>
<a href="http://eclipse.org">Eclipse.org</a>
</li>
</ul>
</div>
</nav>
</header>
<section class="content">
<div class="container">
<div class="row">
<div class="col-sm-3">
<div class="rcptt-sidebar">
<ul class="nav">
<li class="active" ><a href="https://www.eclipse.org/rcptt/documentation/userguide/getstarted/">Get Started</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/testeditor/">Test Case Editor</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/controlpanel">Control Panel</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/assertions/">Assertions</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/">Eclipse Command Language</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/new-command-guide/">New ECL Command Guide</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/excel-import-export/">ECL commands for Excel import and export</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/xml-import-export/">ECL commands for XML import and export</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/">Contexts</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/workspace/">Workspace</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/workbench/">Workbench</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/launch/">Launch</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/preferences/">Preferences</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/parameters/">Parameters</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/group/">Group</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/folder/">Folder</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/default/">Default</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/super/">Super</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/ecl/">ECL Script</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/">Verifications</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/text/">Text</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/treetable/">Table/Tree</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/errorlog/">Error Log</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/time/">Time</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/procedures/">Procedures and Variables</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/runner/">Test Runner</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/runner/arguments/">Arguments</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/maven/">Maven plugin</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/">RAP</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/install/">Install instructions</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/recordReplay/">Record and Replay</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/capability/">Capability Contexts</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/rap-commands/">ECL commands</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/rap-maven/">Maven plugin</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/integration/test-rail-integration/">Integration with TestRail</a>
</li>
</ul>
</div>
</div>
<div class="col-sm-9">
<h1>Getting Started</h1>
<p></p>
<p>To get an impression what it looks like to work with RCPTT, you'll need the following:</p>
<ul>
<li>RCP Testing Tool IDE (<a href="https://eclipse.org/rcptt/download">download it here</a>).</li>
<li>Eclipse-based application to test. This guide assumes that you are using Eclipse Classic standard package, which can be downloaded from <a href="http://eclipse.org/downloads">Eclipse downloads</a>.</li>
</ul>
<h3 id="launch-rcptt-ide">Launch RCPTT IDE</h3>
<p>Just like usual Eclipse packages, RCPTT IDE does not require installation and can be just unpacked anywhere. So, at first download and unpack RCPTT IDE and your application-under-test somewhere on disk and launch RCPTT IDE.</p>
<p>When you launch RCPTT IDE, you'll be prompted for a workspace location. If you don't know what is workspace in a context of Eclipse application, then just choose the default one (which is rcpttWorkspace folder in your Home directory).</p>
<h3 id="add-an-application-under-test">Add an application-under-test</h3>
<p>To be able to record and replay tests in an application, RCPTT IDE should launch application by itself. To add an application-under-test, go to <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-applications.gif"></img> Applications</span> view and click <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-new-aut.gif"></img> New&#8230;</span> button on View toolbar (alternatively, you may right-click anywhere inside a view and choose <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-new-aut.gif"></img> New&#8230;</span> in a context menu).</p>
<p>In a dialog open, browse for an application-under-test (AUT) location on a disk. Once RCPTT IDE analyzes an AUT, it will automatically set its name to AUT's product id, however you may change it to whatever you like.</p>
<p>Click <span class="uiElement">Finish</span> in a wizard and double-click newly created application-under-test to launch it. Now we are ready to create a first test case.</p>
<h3 id="creating-new-test-case">Creating new test case</h3>
<p>RCPTT stores test cases just as usual files on a file system, so that they can be easily stored in version control system, copied, merged between branches, etc. So in order to create a test case, it is required to create an RCPTT Project first.</p>
<p>Go to <span class="uiElement">File &#8594; New &#8594; <img src="https://www.eclipse.org/rcptt/shared/img/ui-rcptt-project.png"></img> RCP Testing Tool Project&#8230;</span>, type any name, for example <strong>First Project</strong>, and click <span class="uiElement">Finish</span>.</p>
<p>Once a project is created, right-click it in <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-workspace.gif"></img> Test Explorer</span> and select <span class="uiElement">New &#8594; <img src="https://www.eclipse.org/rcptt/shared/img/ui-test.gif"></img> Test Case</span>. Again, type any name, like <strong>First Test</strong>, and click <span class="uiElement">Finish</span>.</p>
<h3 id="record-a-test-case">Record a test case</h3>
<p>RCPTT focuses on a productivity, and RCPTT team puts a great effort to make recorder as best as possible. So while it is possible to write a test script by hads, typically it is much faster to simply record actions and assertions, and then modify recorded script if necessary.</p>
<p>While it might sound a bit boring, as we are starting from scratch, let's create a very simple test case, which creates new Java project and makes sure that this project contains an empty source folder. Before starting recording, make sure that AUT is in <em>Java</em> perspective (don't worry, we'll show how to make sure test case automatically runs with necessary perspective pretty soon).</p>
<p>To make it easier for others to understand what a test case does, we can put a description of test case intention and performed actions into <span class="uiElement">Description</span> section of a test case. Also we can change its name in an editor to <strong>New Java Project</strong> (note that once you save a test case, the name in <span class="uiElement">Test Explorer</span> updates accordingly).</p>
<p>To start test case recording, simply click a <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-record.gif"></img> Record</span> button in test case editor. Once RCPTT goes to recording mode, the main RCPTT window minimizes itself and shows a <a href="#">Control Panel</a>, so it is more convenient to interact with an application-under-test.</p>
<p>So, once recording started, simply do the following actions:</p>
<ol>
<li>Select <span class="uiElement">File &#8594; New &#8594; Java Project</span> in main menu</li>
<li>Type <kbd>sample</kbd> into project name field</li>
<li>Click Finish</li>
<li>Once project is created, expand it in <span class="uiElement">Package Explorer</span>. </li>
</ol>
<p>Note that <span class="uiElement">Control Panel</span> contents is getting updated with recorded actions, but it doesn't include a tree item expansion action, as it assumes that this action is not really important enough.</p>
<p>Once we recorded actions, we also need to assert the state of the UI to make sure that the result of our actions is what we expect. To do this, we need to switch to <em>Assertion Mode</em> on Control Panel toolbar (). Once in Assertion mode, you can click on any UI element on a screen and get an <span class="uiElement">Assertion Window</span> with element's properties. At this point, we are interested in <strong>src/</strong> folder, so click on it, check an <strong>itemCount</strong> in Assertion Window, and click <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-add.gif"></img> Add</span> button.</p>
<p>Once we are done, go to Control Panel toolbar, <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-stop.gif"></img> Stop</span>, <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-save.gif"></img> Save</span> and <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-home.gif"></img> Return to RCPTT</span>.</p>
<p>Now, let's replay the resulting test, but before make sure to manually remove project <kbd>sample</kbd> from AUT's workspace and file system &ndash; we'll cover how to eleminate this manual step in a few minutes.</p>
<p>To replay a test case, simply click a <span class="uiElement">Replay <img src="https://www.eclipse.org/rcptt/shared/img/ui-replay.gif"></img></span> button in a test case editor. An <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-execution-view.png"></img> Execution</span> view will display test result.</p>
<h3 id="ecl-script-intro">ECL Script Intro</h3>
<p>Before we go to <a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/">Contexts</a>, let's take a look at recorded script:</p>
<p></p>
<pre ><code class="language-ecl">&#x200b;get-menu "File/New/Java Project" | click
with [get-window "New Java Project"] {
get-editbox -after [get-label "Project name:"] | set-text sample
get-button Finish | click
}
get-view "Package Explorer" | get-tree | get-item "sample/src"
| get-property childCount | equals 0 | verify-true
</code></pre>
<p>It's probably is understandable intuitively, but here's a brief description how does it work. A scripting language we use, <a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/">ECL</a> (which stands for Eclipse Command Language), is inspired by TCL and Powershell, and it consists of commands, connected by pipes.</p>
<p>A command takes some input, arguments and optionally writes something to an output. A pipe (<code class="language-ecl">&#x200b;|</code>) can be used to redirect an output of the left command to the input of the right command. So, a line <code class="language-ecl">&#x200b;get-menu &quot;File/New/Java Project&quot; | click</code> works like this:</p>
<ol>
<li><code class="language-ecl">&#x200b;get-menu</code> command accepts a menu path (with segments separated by slashes) as an argument. Since there is no input (i.e. it is a first command in a pipeline), it assumes that given menu path addresses an application's main menu. So it makes sure that such menu path exists, and writes a reference to this menu item into its output.</li>
<li><code class="language-ecl">&#x200b;click</code> command takes a control reference from its input and sends events to emulate user's click</li>
</ol>
<p>Next, get on a next line of a script, <code class="language-ecl">&#x200b;with</code> command. Here we can see two important things:</p>
<ol>
<li>An <em>output</em> of a command can be passed as an argument to another command by using square braces (i.e. <code class="language-ecl">&#x200b;[some-command]</code>).</li>
<li>A <em>command</em> itself can be passed as an argument to another command by using curly braces (i.e. <code class="language-ecl">&#x200b;{ some-command }</code>).</li>
</ol>
<p>So, the <code class="language-ecl">&#x200b;with</code> command works like this:</p>
<ol>
<li>Takes an <em>object</em> as a first argument</li>
<li>Takes a <em>script</em> (just a sequence of pipelines) as a second argument</li>
<li>Executes a <em>script</em> by prepending an <em>object</em> to an output of each command.</li>
</ol>
<p>In our test case above, a reference to a window is passed as an input to all commands in with-block, so that we don't need to explicitly tell each command that it should use a window as an input.</p>
<p>Another use of square braces in a script above, is identifying an editbox (<code class="language-ecl">&#x200b;get-editbox -after [get-label &quot;Project name:&quot;]</code></code>). When we locate a textual input, we cannot rely on its text contents, so we are identifying it by its relative location to a label, hence we pass a label control (output of <code class="language-ecl">&#x200b;get-label</code> command) as an argument to <code class="language-ecl">&#x200b;get-editbox</code>. Also this line illustrates that commands may have named arguments, here <code class="language-ecl">&#x200b;-after</code> is an argument name, while <code class="language-ecl">&#x200b;[get-label ...]</code> is argument value.</p>
<p>The last line, which has been recorded when we clicked <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-add.gif"></img> Add</span> button in an <span class="uiElement">Assertion Window</span>, should be pretty understandable now -- it takes a property from an object and verifies that its value is what we expect.</p>
<h3 id="contexts">Contexts</h3>
<p>While creating and running our test case, we had to make manual actions to make sure that our test case passes, and we promised to show how to eleminate it to make a test case fully automated. So, two things we need to fix, are the following:</p>
<ol>
<li>Make sure that there's no project <kbd>sample</kbd> in Workspace</li>
<li>Make sure that current perspective is Java</li>
</ol>
<p>In other words, our test case makes certain assumptions about an application state, and we need somehow to make sure that an application state matches to test case expectations. For this purpose, RCPTT has <a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/">contexts</a>. There are several different types of contexts, which describe different parts of an application state, but in this guide we'll focus on two of them &ndash; <a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/workspace/">Workspace</a> and <a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/workbench/">Workbench</a>.</p>
<h3 id="workspace-context">Workspace Context</h3>
<p>As it can be guessed by its name, Workspace Context is used to describe a state of an application's workspace. To create a workspace context, follow these steps:</p>
<ol>
<li>Right-click RCPTT project in <span class="uiElement">Test Explorer</span>.</li>
<li>Select <span class="uiElement">New &#8594; <img src="https://www.eclipse.org/rcptt/shared/img/ui-context.gif"></img>Context </span>. </li>
<li>In a <span class="uiElement">New Context Wizard</span>, type <kbd>Empty Workspace</kbd> as a context name and select <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-workspace.gif"></img> Workspace</span>.</li>
<li>Click <span class="uiElement">Finish</span>.</li>
</ol>
<p>You can see in workspace context editor that it is empty by default and it has an option <span class="uiElement">Clear workspace</span> turned on by default, so we don't need to do anything else with it, we just need to associate our test case with this context.</p>
<p>There are two ways to do that with a test case editor:</p>
<ul>
<li>Use <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-add.gif"></img> Add&#8230;</span> button on a <span class="uiElement">Contexts</span> section toolbar and select required context from context selection dialog.</li>
<li>Expand <span class="uiElement">Contexts</span> section, drag a context from <span class="uiElement">Test Explorer</span> and drop a context inside.</li>
</ul>
<p>It is not necessary to run a test case to see a context in action &ndash; use <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-replay.gif"></img> Apply</span> button in context editor to see how a context affects an application state. In our case, we can see that applying an empty workspace context indeed removes all projects from application workspace.</p>
<h3 id="workbench-context">Workbench Context</h3>
<p>Workbench context is used to describe a state of an application Workbench &ndash; which perspective is currently active and which views and editors are open. For our test case we need to specify that Java perpspective is open. To create a workbench context describing this, do the following:</p>
<ol>
<li>As with workspace context, create a new context named <kbd>Java Perspective</kbd> of <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-workbench.gif"></img> Workbench</span> type.</li>
<li>In workbench context editor, use <span class="uiElement"><img src="https://www.eclipse.org/rcptt/shared/img/ui-capture.gif"></img> Capture</span> button to make a snapshot of a current application state. Assuming that Java perspective is open, the contents of a workbench text editor should be populated with a Java perspective and open views.</li>
</ol>
<p>Now, once a test case refers to two contexts, we don't need to do any manual steps to make test case passing &ndash; it can be successfully replayed several times in a row.</p>
<p>Contexts are highly important for RCPTT test cases and greately improve QA Engineer productivity and overall reliability of test base.</p>
<ul>
<li><em>Contexts can be reused</em> &ndash; multiple test cases can refer to the same context. Thus it is possible to create a set of contexts describing an application state and create as many test cases starting from this state as necessary.</li>
<li><em>Contexts isolate test cases from each other</em> &ndash; if some test case fails, it won't affect further test cases, allowing to get rid of false negative results.</li>
</ul>
<h3 id="conclusion">Conclusion</h3>
<p>In this guide we have covered how to add and launch an application under test, how to create and record test cases, how to add assertions for properties of UI elements, how a test script looks like, how to create and capture contexts and add them to test cases. For more information on these topics, browse a documentation reference using a navigation tree on a left.</p>
</div>
</div>
</div>
</section>
<script src="https://www.eclipse.org/rcptt/shared/js/main.js"></script>
</body>