blob: 6a5a581ec54009816f7ebfbe56626e2a379f09a9 [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 ><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 class="active" ><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>Procedures and Variables</h1>
<h3>Introduction</h3>
<p>
While automated recording in RCPTT works well, a lot of advanced users prefer to write ECL scripts manually,
as it allows to create more flexible and maintainable test cases. So we have significantly
improved the expressive power of ECL by introducing user-defined variables (via let blocks) and user-defined procedures
(via proc commands). Before going into details, here's a simple example - suppose we are testing Java editor and would
like to hover a ruler on a currently selected line. Here's how it can be done without using variables in a plain old ECL:</p>
<pre ><code class="language-ecl">&#x200b;get-editor "Program.java" | get-left-ruler |
get-ruler-column AnnotationColumn | hover-ruler
[get-editor "Program.java"] | get-text-viewer |
get-property "caretPosition.line" -raw]
</code></pre>
<p>This is not so much easy to write, and, what is more impotant, not so easy to understand.
Now take a look how the same actions can be expressed using variables:</p>
<pre ><code class="language-ecl">&#x200b;with [get-editor "Program.java"] {
let [val currentLine
[get-text-viewer | get-property "caretPosition.line" -raw]]
[val rulerColumn
[get-left-ruler | get-ruler-column AnnotationColumn]] {
$rulerColumn | hover-ruler $currentLine
}
}
</code></pre>
<p>And if we need to do this operation multiple times in different scripts, we can rewrite it to a procedure:</p>
<pre ><code class="language-ecl">&#x200b;proc "hover-current-line" [val editor -input]
[val columnName "AnnotationColumn"] {
with $editor {
let [val currentLine
[get-text-viewer | get-property "caretPosition.line" -raw]]
[val rulerColumn
[get-left-ruler | get-ruler-column $columnName]] {
$rulerColumn | hover-ruler $currentLine
}
}
}
// Hover Annotation column:
get-editor "Program.java" | hover-current-line
// Hover Projection column:
get-editor "Program.java" | hover-current-line ProjectionRulerColumn
</code></pre>
<h3>Let</h3>
<p>
Variables are immutable and once set, their value cannot be changed, so probably it it more correct to name them as 'named values',
but we are going to use a term 'variable' as it more familiar and recognizable. 'let' command allows to declare an arbitrary number
of variables and then execute a script referring these variables. Variables are visible only in a script, passed to a 'let' command. Here's a
simple example of a 'let' block, which declares a variable 'foo' and shows a message box with its value:</p>
<pre ><code class="language-ecl">&#x200b;let [val foo "Hello, world!"] {
show-alert $foo
}
</code></pre>
<p>We can put as many 'val' declarations as required, and specify a result of another command as a value.
So, in a script below we store a result of 'get-window' invocation in a variable 'window':</p>
<pre ><code class="language-ecl">&#x200b;let [val button OK] [val window [get-window "New project"]] {
$window | get-button $button | click
}
</code></pre>
<p>Also, it is possible to take a value of a variable from an input pipe by specifying '-input'
argument after variable name. In this case, the value of a variable will be taken from an input pipe of a 'let' command:</p>
<pre ><code class="language-ecl">&#x200b;emit "Hello, wrold!" | let [val msg -input] { show-alert $msg }
</code></pre>
<p>This might be particularly useful in a combination with 'foreach' command:</p>
<pre ><code class="language-ecl">&#x200b;with [get-view "Package Explorer" | get-tree] {
collapse-all
get-items | foreach {
let [val item -input] {
format "project %s" [$item | get-property "caption" -raw] | log
}
}
}
</code></pre>
<p>Let blocks also can be nested:</p>
<pre ><code class="language-ecl">&#x200b;let [val foo "Hello"] {
let [val bar "world"] {
show-alert [format "%s, %s!" $foo $bar]
}
}
</code></pre>
<h3>Proc</h3>
<p>Similar to TCL language, a command <a href="http://download.eclipse.org/rcptt/release/1.5.4/doc/ecl/index.html#proc">proc</a> can be used to declare a user-defined procedure.
It takes a procedure name, parameters and body as arguments. Once 'proc' command is executed, a new command
with a procedure name becomes available and can be executed as any built-in ECL command. Because of current ECL syntax restriction,
if a procedure name contains a '-' character, its value should be enclosed into double quotes during declaration.
However, to invoke a procedure, double quotes are not required (and even prohibited). Here's an example of a procedure without arguments:</p>
<pre ><code class="language-ecl">&#x200b;// declaring procedure:
proc "hello-world" {
show-alert "Hello, world!"
}
// invoking procedure:
hello-world
</code></pre>
Procedures can have any number of arguments:
<pre ><code class="language-ecl">&#x200b;// Declaration:
proc "close-window" [val title] [val button] {
get-window $title | get-button $button | click
}
// Invocation:
close-window "New Project" "OK" // ordered args
close-window -button "OK" -title "New Project" // named args
</code></pre>
<p>Procedures can define 'input' arguments and default values for arguments:</p>
<pre ><code class="language-ecl">&#x200b;// Declaring
proc "set-text-after-label" [val parent -input] [val label] [val text ""] {
$parent | get-editbox -after [get-label $label] | set-text $text
}
// Using &ndash; text arg is not set, so default value will be used
get-window "New Project" | set-text-after-label "Project name:"
</code></pre>
<h3>ECL and RCPTT</h3>
<div class="panel panel-default">
<div class="panel-body">
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-procedures-12.png"></img>
</div>
</div>
</div>
<p>All changes described above are available in core ECL and available when ECL is used without RCPTT,
however, when it comes to RCPTT, it becomes even more powerful:</p>
<ul>
<li>Procedures can be declared in ECL contexts, and in this case they will be available to all test cases, referring to declaring context</li>
<li>Values declared in Parameter contexts can be accessed in the same way as variables, using $-syntax</li>
<li>ECL and parameter contexts can be added to <a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/default/">default contexts</a>, and therefore, automatically become available in all test cases in given project</li>
<li>Test case and ECL editors support completion, navigation and documentation for procedures, variables in 'let' blocks and parameter names from <a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/parameters/">parameters contexts</a></li>
</ul>
<p>A sample project, illustrating the expressive power of procedures is available on GitHub - https://github.com/xored/q7.examples.procs.
You can run a test case from this project on your machine by executing the following commands in shell:</p>
<div class="panel panel-default">
<div class="panel-body">
$ git clone https://github.com/xored/q7.examples.procs.git<br>
$ cd q7.examples.procs<br>
$ mvn clean package<br>
</div>
</div> </div>
</div>
</div>
</section>
<script src="https://www.eclipse.org/rcptt/shared/js/main.js"></script>
</body>