Assertion

Assertion nodes are used in writing tests. Each Assertion node consists of several assertions - statements that allow you to test certain assumptions. When you run an Assertion node, you run all assertions. If any test raises an error, the entire Assertion node run is unsuccessful.

An Assertion node can only be created as a child of a RequestStep node. At the same time, a RequestStep node can have only one Assertion node as a child.

There are two ways to create an Assertion node. First, choose Add node -> Assertion from a RequestStep node context menu. Second, click + CREATE NEW ASSERTION NODE on the Assertion tab of the RequestStep node response area.

This is how an Assertion node looks like in the project tree:

If an Assertion node was run successfully, its icon in the project tree looks like that:

If an Assertion node was run unsuccessfully, its icon in the project tree changes to this:

There are several actions you can do with this node type:

  • Remove node. Use it to delete the node.

  • Run. Run the node.

  • Show in explorer. Open the folder with the node in the file manager.

The Assertion node tab has the following interface:

In the screenshot you can see the following parts of the interface:

  1. The control panel

  2. The settings panel for the chosen assertion

  3. The list of all assertions

You can see the following buttons on the control panel:

  • RUN - runs all assertions in the list.

  • FIX ERRORS - fixes assertions errors if possible The button is available if there are some errors in the assertions. The error fixing algorithms are described for each assertion type separately.

  • DISABLE ERRORS - disables the failed assertions. They won't be included in further runs. The button is available if there are some errors in the assertions.

  • + ADD ASSERTION - adds an assertion to the list.

The assertions list is right under the control panel. Each element of the list has the looks like this:

In the screenshot you can see the following parts of the interface:

  1. Status highlighting. Its status is gray, if the assertion hasn't been run yet, red - if the run failed, green - if it was successful.

  2. Drag-and-drop point.

  3. The assertion type icon.

  4. The assertion text representation.

  5. Show/hide error details button.

  6. Delete the assertion.

  7. Disable the assertion. It won't be included in the further runs.

  8. Run the assertion.

  9. Fix the assertion.

Note that the controls 6, 7, 8, and 9 appear when you hover the mouse over the assertion.

The interface of the settings panel depends on the chosen assertion type. We'll discuss all of them in the next sections.

Each Assertion has a Name field to specify what is being tested. If the field is empty, a default description is set according to the assertion properties.

Assertion Template

Starting from the 1.0.0 version, an Assertion node may be created without any connection to a RequestStep node, as any other node in the project. It can be used for checking results of multiple requests or as a template where a set of standard assertions is defined.

As compared to an Assertion which is related to a RequestStep node and inherits its context (variables, dynamic variables, response), an assertion template inherits the context of the node which refers to this template while running. The context is saved to the $host built-in variable and is initialized only after running.

Running an assertion template separately doesn't make any sense, since there is no context available and all assertions are going to be failed. For this reason, we eliminate this possibility in TestMace, and nodes of this type will be skipped while running scenarios.

For debugging purposes, in the template interface you'll see the name of the node that was run last and sent its context to the template. In this case, values highlighting and autocomplete for every expression containing the $host variable will be available.

To learn more about using independent Assertion nodes as templates and to see some examples of that, please refer to the Link Assertion section.

File Representation

An Assertion node is stored in the <nodename>.yml file, where <nodename> is the Assertion node name. The file has the following format:

{
  "type": "object",
  "properties": {
    "type": {
      "description": "Type of Assertion node",
      "const": "Assertion",
      "type": "string"
    },
    "assertions": {
      "description": "List of assertions",
      "type": "array",
      "items": {
        "$ref": "#/definitions/AbstractAssertion"
      },
      "default": []
    },
    "children": {
      "description": "List of children names",
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "variables": {
      "$ref": "#/definitions/NodeVariables",
      "description": "Node variables dictionary"
    },
    "name": {
      "description": "Node name",
      "type": "string"
    }
  },
  "required": [
    "assertions",
    "children",
    "name",
    "type",
    "variables"
  ],
  "definitions": {
    "AbstractAssertion": {
      "oneOf": [
        {
          "$ref": "#/definitions/CompareAssertion"
        },
        {
          "$ref": "#/definitions/ContainsAssertion"
        },
        {
          "$ref": "#/definitions/XPathAssertion"
        },
        {
          "$ref": "#/definitions/ScriptAssertion"
        }
      ]
    },
    "CompareAssertion": {
      "type": "object",
      "properties": {
        "type": {
          "description": "Type of Compare assertion",
          "const": "compare",
          "type": "string"
        },
        "actualValue": {
          "description": "Actual value",
          "type": "string",
          "default": "${$response.body}"
        },
        "operator": {
          "$ref": "#/definitions/CompareOperator",
          "description": "Operator",
          "default": "equal"
        },
        "expectedValue": {
          "description": "Expected value",
          "type": "string"
        },
        "disabled": {
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "actualValue",
        "disabled",
        "expectedValue",
        "operator",
        "type"
      ]
    },
    "CompareOperator": {
      "enum": [
        "equal",
        "greater",
        "greater or equal",
        "less",
        "less or equal",
        "not equal"
      ],
      "type": "string"
    },
    "ContainsAssertion": {
      "type": "object",
      "properties": {
        "type": {
          "description": "Type of Contains assertion",
          "const": "contains",
          "type": "string"
        },
        "text": {
          "description": "Text to be searched",
          "type": "string",
          "default": "${$response.body}"
        },
        "value": {
          "description": "Value for search in text",
          "type": "string"
        },
        "disabled": {
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "disabled",
        "text",
        "type",
        "value"
      ]
    },
    "XPathAssertion": {
      "type": "object",
      "properties": {
        "type": {
          "description": "Type of Xpath assertion",
          "const": "xpath",
          "type": "string"
        },
        "text": {
          "description": "Text to be searched",
          "type": "string",
          "default": "${$response.body}"
        },
        "path": {
          "description": "XPath selector",
          "type": "string"
        },
        "expectedValue": {
          "description": "Expected value",
          "type": "string"
        },
        "disabled": {
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "disabled",
        "expectedValue",
        "path",
        "text",
        "type"
      ]
    },
    "ScriptAssertion": {
      "type": "object",
      "properties": {
        "type": {
          "description": "Type of Script assertion",
          "const": "script",
          "type": "string"
        },
        "script": {
          "description": "Assertion script",
          "type": "string",
          "default": "`function test(assertion, variables) {\n  // It should return true if test is passed\n  // return true;\n}`"
        },
        "disabled": {
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "disabled",
        "script",
        "type"
      ]
    },
    "NodeVariables": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Last updated