Attachment Element/en

Aus expecco Wiki (Version 2.x)
(Weitergeleitet von Attachment Element)
Zur Navigation springen Zur Suche springen

Introduction[Bearbeiten]

An attachment allows managing a file or URL reference together with a test suite. The attachment's file contents can either be packed and bundled into the test suite (which is technically a ZIP file) or alternatively fetched dynamically (during test execution) from an external web source. The later are called "URL Attachments". File attachments are important, if test data sets or configuration files have to be managed together with the test suite. They can also contain files which are meant for other users, such as documentation or specifications and explanations concerning test runs.

All attachments will be unpacked in a separate folder named "attachments" under a project-specific directory when the test suite is loaded (which is useful to know, if they are to be accessed by scripts or elementary code).

Therefore, an attachment's filename should usually consist of the base-filename only (i.e. do not use a full absolute path). If the attachment has an absolute path, expecco will not pack it into the .ets - test suite file, and assumes that the file is created elsewhere and already present; for example by checking out configuration files from the source repository, or by fetching them from another host's mounted file system.

Attachment in an Activity Diagram[Bearbeiten]

When an attachment is dragged into a compound action's network, an attachment-reading step action is generated. When triggered or autostarted, this attachment step provides the file's name or contents at its output pin. Thus, the attachment step behaves just like any other step in the diagram.

The step is configurable to either provide the filename or its contents at its output pin. The default is to generate the filename. Thus, to get the full path of an attachment, make sure that the output representation is set to "pathName" and connect the attachment step's output to whichever step needs the path.

Point right.png Notice that all of the attachments' filenames must be distinct. For that, the name of the file is not required to be the same as the item's name in the navigation tree. When copy-pasting or dragging attachments into the tree, expecco may silently change the filename (but not the name), if another attachment already exists by that filename. In that case, the underlying filename may be different from its name shown in the tree. Thus, you should never use the tree item's name, but always refer to its filename (via the output pin).

In most situations, you will not need the file's actual path, but its contents instead. Choose an appropriate output representation from the steps context menu. Typically, this will be one of "string", "utf8 string" or "binary". See the list below for details.

Importing Attachments[Bearbeiten]

Beside just creating a new attachment and specifying its underlying file afterwards in the attachment editor, attachments can be also added to the project tree via drag and drop of any file into the navigation tree area. They can at any time later be modified in the built-in attachment editor or by an external tool (Excel, Notepad etc.).

Finally, if you have to import many files, use the "Import Attachments" menu function from the "Extras" → "Import" menu item.

Use of Absolute Filenames[Bearbeiten]

If an absolute path is given as filename, the underlying file is assumed to be generated by some other program (possibly on the fly, during execution) or already present. These files are considered "extern to expecco", and are not saved with or inside the ".etf" test suite file. Use this, to access configuration data which is supposed to be already installed on the test host, or which is created dynamically, for example due to the execution of a supporting external program.

Because absolute pathnames are considered harmful (you may forget to save/restore/install them, or two simultaneously running tests may corrupt each other's data) the project tree's error-search function includes a "Search-for-absolute Attachments" check box, to quickly locate such attachments.

URL Attachments[Bearbeiten]

URL attachments are fetched dynamically during execution time via an HTTP-Get request from the specified URL (other access methods may be added in future versions). A runtime error will be raised, if that file is no longer accessible. URL attachments are therefore somewhat dangerous: your test depends on another external resource. Therefore, it is recommended to fetch the URL once during test-development time, and to add it as a regular attachment to the test suite (unless the fetch operation is actually part of your test).

Data Representation[Bearbeiten]

When an attachment is dropped into an activity diagram, an attachment step is created with a single output pin. When that step is executed (either via a trigger input or by marking it as autostart), the underlying file information is provided at the output pin. Depending on what further processing is to be done to that file data, different data values may be desired. For this, the attachment step's context menu in the diagram editor offers various choices (via the "Output Data Representation" context menu item) for how the attachment's file should be presented at the steps output pin:

PathName as String
The pathname of the file is provided at the output. To get to the contents, additional processing steps (File Contents, CSV decoding, Filestream reading) are usually required. However, if the file is to be passed to an external program or batch script, often the pathname is sufficient as command line argument. Notice that unless an absolute path is given, the path refers to a temporary file which is created when the test suite is loaded, and which will be removed when either another suite is loaded, or the expecco application is terminated.
UNIX PathName as String
The pathname of the file is provided as a UNIX filename at the output. If expecco is running under Linux or OSX, this is the same as the above. However, if executed under Windows, the presented filename will contain "/"-characters as directory separators instead of "\". Use this, if the file's name is to be passed to a remote program or to an external script interpreter which expects unix file names.
PathName as Filename Object
Same as above, but an instance of Filename (see primary data types) is generated.
As URL
generates a URL of the form "file://<path>"
String (Contents as String)
the file is read into one (possibly big) single-byte string. No decoding is performed. This representation may not be appropriate for UTF-8 encoded files, if your intent is to process the contents. However, it is most useful, if the contents is to be passed on to other processing steps, passed to external programs, or to be send out via a socket. If the contents is shown in expecco, or processed by any of expecco's functions, it is interpreted as ISO8859 encoded.
UTF8 String (Contents as UTF-8 String)
the data is read as a single string, and interpreted as an UTF-8 encoded string. The output may be a single-byte or a multi-byte string, depending on the presence of characters with a codepoint > 255.
StringCollection (Contents as Collection of Lines)
the file is read into a collection of single-byte string lines. No decoding is performed.
Linewise (Contents as Individual Lines)
the file is read line-wise, and each line is send to the output pin as a separate datum. This will trigger follow-up actions once for every line in the original document.
Binary
the file is read into a single ByteArray collection. Use this for binary data.
Bitmap Image
the file is assumed to contain a bitmap image in one of the supported formats (PNG, JPEG, GIF, TIFF and many others).
JSON Object
a single JSON object is read from the file and presented at the output
Multiple JSON Objects
multiple JSON objects are read from the file and presented at the output

The following representations are only possible with URL attachments. They automatically decode the fetched document into the expecco internal Unicode format, from a number of common document encodings (for example, ISO 8859-x, UTF-8, ASCII, and many other).

DecodedString (URL Attachment only)
the URL is fetched as a single string, which is converted as specified by the encoding answer (from the HTTP request). The output my be a single-byte (for ASCII or ISO 8859-1 encodings) or a multi-byte string (for most other encodings, especially for UTF-8). Use this if follow-up actions are to process this data.
Decoded StringCollection
Same as StringCollection, but each line is decoded from an encoding as returned by the HTTP request.
Decoded Linewise
Same as Linewise, but each line is decoded from an encoding as returned by the HTTP request.

Notice, that only URL attachment steps provide an automatic determination of the document's encoding (because it gets this information with the HTTP response). For file documents and very special unsupported encodings, you should set the representation to "binary" and connect the output pin to an explicit conversion action. You may find an appropriate decoder block in the standard library, or write your own as an elementary block.

Editing an Attachment's Contents[Bearbeiten]

Attachments can be edited using the attachment editor, which is shown when an attachment tree item is selected. For most simple textual formats, the builtin text editor is sufficient. However, if you prefer your own editor, or a special editing application is to be used, you can configure the editor as-per-mime type in the "external tools" configuration dialog. Details are found in the attachment editor's documentation.

Encrypting an Attachment's Contents[Bearbeiten]

New with version 21.1:
It may be useful to keep login/password data in an attachment, although you don't want to get them exposed, in case the suite gets copied to unauthorized users. For this, you can encrypt an attachment's contents, to be only readable, if the user provides a correct password whenever the document's contents is fetched later. Expecco will use one single password to encrypt all documents within a suite, and will ask when the first such access happens. The password will be remembered for the duration of the session.

The encrypt function is found in the context menu of the attachment's tree item.

Special Attachments (Wellknown Attachment Types)[Bearbeiten]

Expecco uses attachments with special tags to hold eg. configuration data. These are recognized by their special (and wellknown) tag:

  • GUI_CONFIGURATION
    these contain GUI configurations (eg. a setup with multiple GUI connections to be (re-)established as a whole. These are used with complex UI tests, in which multiple UIs are controlled and/or verified within a test setup.
  • GUI_SCREENPLAY
    these contain GUI element mappings from logical names to locators. Depending on the UI connection, these locators are usually either xPath locators, or bitmap locators.



Copyright © 2014-2024 eXept Software AG