# 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](https://docs.testmace.com/node-types/request-step) node. At the same time, a [RequestStep](https://docs.testmace.com/node-types/request-step) 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](https://docs.testmace.com/node-types/request-step) node context menu. Second, click **+ CREATE NEW ASSERTION NODE** on the Assertion tab of the [RequestStep](https://docs.testmace.com/node-types/request-step) node response area.

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OUEAQYHhMlYdD6sWU%2Fimage.png?alt=media\&token=d2cd2214-3fda-4c63-8c19-f68174c9ec37)

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

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OUH0tP1IpwYRfZOYL%2Fimage.png?alt=media\&token=c2aa7ec6-baa9-4b00-933c-5a86f6cf32ed)

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

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OUJgFbOIDapcawe0x%2Fimage.png?alt=media\&token=57f77d49-6e4d-4fa8-a423-1bd7c3c74e1b)

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

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OULyt2yu1CEMyRZBL%2Fimage.png?alt=media\&token=3c7142b5-1516-41dd-bd6f-3444a951bbe8)

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

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OUOfsA0JDHoaWVS2h%2Fimage.png?alt=media\&token=801bc255-9336-4df6-917e-8048b60d4d64)

* **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:

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OUSpJR6DqVlUXyNuj%2Fimage.png?alt=media\&token=eff860f2-e3b4-41c0-b9d6-641eaa4e7216)

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:

![](https://1550208191-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LYfhIaTTw23Sf3L5jfe%2F-M4OT249rvL-_C8vTTtA%2F-M4OUadm0yLAC_9Q_EVX%2Fimage.png?alt=media\&token=598cb0b1-3ed1-44b4-836f-e56c4f83a5df)

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**.

{% hint style="info" %}
Note that the controls 6, 7, 8, and 9 appear when you hover the mouse over the assertion.
{% endhint %}

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:

```javascript
{
  "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#"
}
```