Difference between revisions of "Expecco Scripting API/en"

From expecco Wiki (Version 2.x)
Jump to navigation Jump to search
(3 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
Often it is not required to implement an elementary action with Smalltalk, JavaScript or Groovy code: there may be already a program (command line tool), a shell script, or a program/library written in another scripting language available.
 
Often it is not required to implement an elementary action with Smalltalk, JavaScript or Groovy code: there may be already a program (command line tool), a shell script, or a program/library written in another scripting language available.
 
Expecco provides convenient, flexible and easy to use mechanisms to call those existing functions or programs.
 
Expecco provides convenient, flexible and easy to use mechanisms to call those existing functions or programs.
  +
  +
Note: be reminded of the [[ ElementaryBlock_Element/en#Bridge_Action_Blocks_vs._Script_Action_Blocks | difference between ''Script Actions'' and ''Bridged Actions'']] (described in the [[ ElementaryBlock_Element/en | "Elementary Block Overview"]])
   
 
== expecco Script API ==
 
== expecco Script API ==

Revision as of 07:53, 13 August 2019

Shell and Script Elementary Blocks[edit]

Often it is not required to implement an elementary action with Smalltalk, JavaScript or Groovy code: there may be already a program (command line tool), a shell script, or a program/library written in another scripting language available. Expecco provides convenient, flexible and easy to use mechanisms to call those existing functions or programs.

Note: be reminded of the difference between Script Actions and Bridged Actions (described in the "Elementary Block Overview")

expecco Script API[edit]

The way external scripts are called is similar with all supported scripting languages. Depending on the language and script interpreter, there are minor differences in the debug features provided and the format of error messages (these are provided by the called scritp interpreter, and can usually not be enhanced by expecco).

The general mechanism works as follows:

  • every script action has a number of input pins to control:
    • the standard input to be sent to the script ("stdin" pin)
    • a specification of how the output should be handled (all in one, linewise, or in multiple-line chunks)
    • an optional execution directory ("execDir" pin)
    • an optional set of shell environment variable definitions ("environment" pin)
    • an optional list of command line arguments ("args pin)
    • additional input pins to further parametrize the executed script (see "Parameters" section below)
  • every script action provides at the output:
    • the standard output (at the "stdout" pin) either linewise, all-in-one, or chunked, as specified by the "outNLines" input pin
    • the standard error ("stderr" pin), also as specified by the "errNLines" input pin
    • the program's exit code ("result" pin)
    • an optional converted output value ("stdoutValue" pin)

All of those pins and their behavior are described below.

When initially created (via the tree-menu), a script action's definition includes all of the above pins if the "Initially Created all Special Pins" flag is checked in the "Look & Feel" - "Diagram-Editor" settings dialog. Otherwise, only the "stdout" pin is created automatically. However, you can at any time remove any unneeded pins in the schema editor, to make your diagrams easier to understand. And any of those pins can be re-added later, via the schema-editor's "Add Special Pin" menu.

Execution[edit]

When executed, the script's code is first expanded, using the any additional parameter input pin values, and the expanded code is written to a temporary file. Then the external script interpreter is called (with optional command line arguments as provided by the "args" pin), with the current directory set to either the specified exec-directory (via the "execDir" pin), or in the project's attachment folder. Having the current directory set to the attachment folder makes it easy for the script to access any attached data files, and also to create output files, which may later be archived in the generated ".elf" file.

When finished, the exitCode is written to the "result" pin (if present). Usually, a zero value means "OK", but the details depend on the called script/command (for example, the Unix "diff" command returns a "1" if there are no differences).

The stdout and stderr are written after the executen iff those pins were defined as buffered pins. If unbuffered, the output and error are written as the script generates them (and will be passed to connected steps even if the script later exits with a non-zero exit code).

Finally, the "stdOutValue" pin provides the stdout string converted to its datatype. For example, if this pin has an "Integer" type, the program's stdout will be converted to an integral number and that converted value be generated at the "stdoutValue" pin. A conversion error might be reported, if the program's output does not represent a valid integer number. Be aware, that this automatic conversion is probably only useful for a very limited set of possible types - typically integers, floats and stringCollections.

Synchronization[edit]

A common application of script blocks is to start an external server program, simulator, protocol framework or other utility, with which expecco needs to interact later. If the program has a startup phase, during which it should not be contacted, a synchronization issue may be encountered: you may want to wait until the started program generates a particular message on either stdout or stderr. Typically, you would wait for some "Service Ready" message, before the test suite should continue and talkt to that subsystem.

For this, two (optional) pins are provided:

  • "prompt_optional" if this pin has a value, it must be a string defining a match pattern or substring. The stdout and stderr will be watched for a line matching this pattern (or containing that substring). When a match is detected, the
  • "prompt_detected" pin will receive that line (unbuffered - i.e. as soon as a match is detected)

Use the "prompt_detected" output as a trigger- or data input to do the actual testing (or to register that the server processes startup procedure is completed)

Shell Scripts[edit]

Hello World as Shell Script[edit]

The first example is the obligatory "hello world" example:

  • create a new shell script action,
  • remove all but the stdout pin,
  • change the code to:
echo "Hello, World"

execute and see the program's output at the "stdout" pin.

Additional Parameter Inputs[edit]

The next example demonstrates parameter passing to the script;

  • add an additional input pin named "greeting" (with type "String")
  • change the script to:
echo "%(greeting)"
  • go to the "Test/Demo" page, and freeze the "greeting" input pin with some arbitrary string (for example: "hello foobar"), or feed it from another step's output,
  • execute the example to see the "greeting" pin's value being echoed.

Accessing Attachment Files[edit]

  • create an attachment, containing a few lines of text:
line1
line2
line3
  • change the filename to "testAttachment". Be careful here: the filename must be "testAttachment" - not the name of the attachment in the tree. Although it does not hurt, if the have the same name.
  • change the script to:
ls -l
cat testAttachment
  • run it to see the attachment folder's name, followed by the lines of the file attachment.

Python Scripts[edit]

The way Python script blocks are used is the same as with shell action blocks. Of course, the script's code must be a valid Python program, and you have to have a python executable installed and either in your path, or its path defined in the "Setting" - "External Tools" dialog.

Perl Scripts[edit]

Perl scripts behave like the other script languages (ensure that a perl interpreter is found along your path, or the path is specified in the settings dialog).

Value Conversion[edit]

This example invokes a Perl script, which generates multiple output lines, which will be available in expecco as a collection of lines.

  • generate a new Perl script action
  • remove all pins except for the "stdout" and "stdoutValue" pins
  • change the datatype of the "stdoutValue" pin to "StringCollection".
  • change the script to:
print "Hello World from a Perl script\n";
print "line1\n";
print "line2\n";
print "line3\n";
print "line4\n";
  • run the script; you'll get the output as one big string at the "stdout" pin, and individual lines at the "stdoutValue" pin

Ruby, TCL, Powershelgl, Go... Scripts[edit]

All of the above applies to those scripting languages as well.

Gnuplot and RScript Action Blocks[edit]

These expect additional "data" pin values. And are described in detail in separate documents ("Using Gnuplot Action Blocks" and " Using R Action Blocks".



Copyright © 2014-2018 eXept Software AG