| <!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> |
| </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">​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">​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">​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">​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">​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">​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">​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">​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">​// 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">​// 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">​// Declaring |
| proc "set-text-after-label" [val parent -input] [val label] [val text ""] { |
| $parent | get-editbox -after [get-label $label] | set-text $text |
| } |
| |
| // Using – 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> |
