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.
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 - for example by checking configuration files from the source repository, or by fetching them from another host's mounted files system.
When an attachment is dragged into a compound action's network, an attachment-reading step action is generated. This attachment step provides the file at its output pin, when triggered or autostarted (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.
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.
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
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 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.
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 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>"
- 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.
- UTF8 String
- the data is read as a single string, and interpreted as an UTF-8 encoded string. The output my be a single-byte or a multi-byte string, depending on the presence of characters with a codepoint > 255.
- the file is read into a collection of single-byte string lines. No decoding is performed.
- 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.
- 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).
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
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.