Perform tests

Overview

To interactively test a published workflow, open it and select the Test tab of the workflow's workspace.

You can also use a published workflow programmatically through the NL Flow API and test it using utilities like Postman. In this case you can download ready to use Postman collections.

Initial test

The first time you visit the Test tab, an empty test is already available. Set its input and run the test.

Set the input

Introduction

The input to a workflow is a JSON that must be either:

Compatible with the input of all the first block of each independent flow.
Compliant with the optional description you or other users have provided in the editor.

It is always possible to write or upload the input JSON, but there are cases in which NL Flow, knowing which input is compatible with the workflow, allows you to specify a much simpler input and generates the JSON by itself when running the test:

If the workflow "wants" a Base64 encoded file and its path, as is the case of a workflow starting with TikaTesseract Converter or Extract Converter, NL Flow allows you to upload a file. When running the test, NL Flow will automatically create the JSON performing the Base64 encoding of the file contents and using the file name as path.
Similarly, if the initial block of the workflow is a model, NL FLow allows you to enter plain text which then it will use to automatically create a basic input JSON containing only the text key, without having to worry about JSON character escaping.

Write or load JSON

It is always possible to enter the workflow input as JSON and sometimes, when the input of the first blocks of the flows has an undetermined structure, it's the only option.

If not already selected, select the JSON input tab.
Enter the JSON in the editor.

Or:
Select Upload file on the panel toolbar to upload a JSON file.

Or:

If you want to compose the JSON using the expected input of the initial blocks of the workflow flows as a guide, open the drop-down list with an empty hexagon icon on the panel toolbar. The list shows all the initial blocks of the workflow's flows.
1. Select a block from the list: the drop-down gets the name and the icon from that block and the next drop-down, that with the key icon, shows the list of input properties of the block.
2. Toggle keys inside the drop down list with the key icon: keys will be added or subtracted from the input JSON accordingly.

Or:

To add or replace a key containing the Base64 encoding of a file:
1. Select Add file content from the drop-down with the key icon on the panel toolbar. A dialog appears.
2. Select Upload file and select the file to encode.
3. Check or change the default name of the key (base64).
4. Select Add.
If a key with the same name is already present in the input JSON it gets replaced.

To clear the JSON editor, select Clear text on the panel toolbar.

Enter or load plain text

To specify plain text as workflow's input, when allowed:

If not already selected, select the Text editor tab.
Enter the text in the text editor. The current size of your text and the maximum size allowed are shown on the panel toolbar.

Or:
Select Upload file on the panel toolbar to upload a text file.

To clear the editor, select Clear text on the panel toolbar.

Upload a file

To a provide a file as workflow's input, when allowed:

If not grayed out, select Upload on the left panel.
Select Browse files at the center of the page.
Select the file.

To choose a different file, repeat the steps above.

Run a test

To take a test:

Set the input.
If the workflow was published in more than one runtime, select Runtime at the bottom right of the page to choose the runtimes—one or more—you want to run the test against.
(Optional) Turn on Workflow debug below the input pane to have an output richer in information about the inner functioning of the workflow.
Select Test workflow at the bottom right of the page.

To watch the progress of the test for an asynchronous workflow, select the Progress tab.
The tab contains the workflow diagram.
The border of the hexagons for which it is possible to detect the progress of the operation is:

Animated, if the block is working or waiting to work
Steady and green if the block has finished its work
Steady and red in case of error

Below this type of hexagon is a numerical indication of the progress.
For example, if a TikaTessercat Converter processor block is inside a context which is iterating on 200 files taken from a ZIP, the indicator will initially be 0/200, then the left part will be incremented up to 200 during the loop. If the block has only one thing to do, however, the initial indication will be 0/1 and will become 1/1 at the end..

If the test takes long you can cancel it by selecting Stop and delete at the bottom right of the page.

In the end:

The left panel is updated with supplementary info, with the possible addition of a test for every runtime beside the first.
The View test results and the Run again buttons are displayed at the bottom right of the page.

Get test info

All tests are listed, from the most recent to the oldest (based on the execution date), in the left panel. In the box dedicated to each test you can find this information:

The name of the test auto-generated by NL Flow, which can coincide with the name of the input file.
A white check mark in a green circle indicating that it is a completed test.

Info

The input of a completed test can no longer be modified.
An icon with concentric hexagons indicating that it is a completed test performed with the debug option enabled.
The date and time of the last execution of the test.
The indication Workflow version updated if the test was performed with the latest version of the workflow, otherwise the indication Older workflow version.
In case of explicit JSON input, the list of top-level keys of the input JSON.
In case of plain text input, the initial portion of the text.
The indication of the runtime.

Repeat a test

To repeat a test that was run against the latest version of the workflow—that is, with the indication Workflow version updated inside the test box—, select the test from the left panel and then select Run again. The test gets repeated, the execution date is updated and the test box is moved to the top of the list in the left panel.
To create and run a new test out of a completed test that was run against an older version of the workflow—that is, with the indication Older workflow version inside the test box—, select the old test on the left panel then select Run new test at the bottom right of the page.

Examine the results

To access the results of a completed test select View test results at the bottom right of the page.

Debug off

If debug mode was turned off, the JSON viewer panel shows the output. Above the panel, an icon represents the type of input.

In case of error, the central panel shows the error message in a sub-panel titled Error viewer.

The left panel lists the top level keys of the output JSON.

In case of a workflow with multiple flows, the keys are grouped according to the last block of each flow, for which the name and ID are displayed.

Selecting a key from this list, the central panel shows only the portion of the overall output JSON corresponding to the selected key, in some cases providing also an enhanced visualization that makes it easier to browse data and provides information on the relationship between output data and the input text.

To filter the list of the output keys, type at least three characters in the search box then press Enter. To clear the filter select the X icon inside the search box.

To restore the visualization of the full output JSON:

Select Full JSON for single-flow workflows.

Or:

Select Workflow result in case of multiple flows.

Debug on

If debug mode was turned on, start time, elapsed time and response size are displayed in the second toolbar from the top inside the central panel.

Verbose output is shown in the Full JSON tab of the central panel.

Response size refers to the verbose output, non verbose output may be much smaller.

Warning

Verbose output can be relatively large. If it exceeds 5MB, you get a warning instead of the full output.

In the first toolbar of the panel from the top, an icon represents the type of input.

To see the JSON input to the workflow, select the Input tab.
To see the non verbose output of the workflow, select the Output tab.

The left panel lists the blocks of the workflow, grouped by flow.

For basic ML models, ML Engine and Symbolic Engine sub-components are listed too.
For each block or sub-component, execution start time and execution elapsed time are displayed.

To see the input and the output of a block, select the corresponding component on the left panel. The output JSON is displayed in the Output tab on the central panel, the input JSON is displayed in the Input tab on the right panel.

In the event of an error with a multi-block workflow, the blocks that gave an error are marked with an exclamation mark and those not executed due to the error are marked with the no-access signal.

Contexts

If the workflow contains the contexts of splitters or remappers, you can navigate the results recursively.
Initially, a context is represented by a box in the left panel corresponding to the block that generated it.
For example, if the workflow contains the context of a splitter, followed by a reducer, initially one box for the splitter and one for the reducer are shown in the left panel. Nothing is initially displayed for blocks contained in the splitter's context.

Selecting the box of a context-generating block:

The Input tab appears in the central panel, showing the input JSON of the block.
In the first toolbar from the top of the central panel, the navigation path of the results of the workflow completed so far is shown, "breadcrumbs" style, with the input type or file as the first portion of the path.
In the second toolbar from the top of the central panel, the start and elapsed times of the block—not of the entire context—are shown.
The left panel lists the items on which the context blocks have iterated. Above the list is the name of the context-generating block.

If you select an item:

A JSON representing the item is displayed in the center panel.
At the top of the left panel and at the end of the breadcrumbs the name of the item is displayed, which is a file name if the item was produced from a ZIP splitter or an artificial name otherwise.
In the left panel the list of items is replaced by that of the blocks of the context executed for the single item.

If during navigation you encounter a nested context-generating block, such as a splitter or a remapper, the above pattern repeats, allowing you to navigate to the most nested blocks of each iteration.

Conditional branches

Also in the case of a Switch block, when browsing the results, all the conditionally executed branches downstream of the Switch block are represented collapsed in the left panel.

All the conditions are displayed and those that were met are marked with a right arrow.

By selecting the Switch block box, the left panel shows the output at the convergence point of the branches, that is at the End Switch block.

By selecting a satisfied condition, the left panel shows the blocks of the corresponding workflow branch and the central panel shows a synthesized JSON, for diagnostic purposes, which represents the followed branch. This JSON contains:

Name, code, comparison operator and evaluated value of the condition.
An executed boolean flag set to true, indicating that the condition has been met and the branch executed.
Diagnostic data of the blocks of the branch, possibly nested. For each block, under the component key, component type, block ID, software service ID, input, output and statistics are indicated.

The first toolbar from the top of the central panel shows a breadcrumbs path corresponding to the condition, while the second toolbar shows the name of the condition.

Detailed statistics on the execution of a block may appear in the right panel. To toggle the display of this information select Toggle statistics on the second toolbar from the top in the central panel.

To navigate backwards:

Select the left arrow preceding the block name in the left panel to make a step back.

Or:

Select anywhere in the breadcrumbs to jump back to the corresponding step.

Common commands

To collapse and expand the left panel showing results, use the collapse button and the expand button on the panel toolbar.

To return to input view, select Back—or the left blue arrow, if the panel is collapsed—on the toolbar of the left panel.

For panels showing output JSON:

To expand or collapse all the sections of the JSON at once, select Expand all or Collapse all on the panel toolbar.
To copy the JSON to the clipboard, select Copy result to clipboard on the panel toolbar.
To save the JSON to a file, select Download result on the panel toolbar.
To expand or collapse a JSON object, select the expand button or the collapse button to the left of the object inside the JSON.

Create a new test

If you have already made tests, whatever their status, you can create a new one.

To create a new test:

Select Create new input, Create or Upload on the left panel.

Or:

Select an old test on the left panel then select Clone input in a new test on the toolbar below the main page toolbar.

Or:

Select a completed test on the left panel that has the indication Older workflow version and then select Run new test at the bottom right of the page to create and contextually start a new test with the same input and the same runtime of the old test, but run against the newest version of the workflow.

Remove tests

To remove a completed test, select it on the left panel then select Delete test on the toolbar below the main one at the top right of the page.

To remove all completed tests, select Clear list at the bottom of the left panel.

Download Postman collections

To download a Postman collection with which you can test a published workflow through the NL Flow API:

Open the workflow
Select the Editor tab or the Test tab.
Select the ellipsis at the end of the toolbar below the main one at the top right of the page then choose one of the runtimes listed under POSTMAN COLLECTION to download a Postman collection withthe pre-sets to user the API for the workflow published in the selected runtime.

Once you have imported a collection into Postman, set collection variable API_KEY with the value of one of the API keys associated to the published workflow.