> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Assertions in TestDriver

> Comprehensive guide to understanding and implementing assertions in TestDriver for robust test validation.

# Guide: Using assertions in TestDriver

Assertions in TestDriver allow you to validate that your application behaves as expected during a test. By using the [`assert`](/commands/assert) command and visual assertions, you can ensure that specific conditions are met, such as verifying the presence of text, images, or UI elements on the screen.

***

## What are assertions?

Assertions are checks that validate whether a specific condition is true. If the condition isn't met, the test will fail, providing feedback on what went wrong.

### Types of assertions in TestDriver:

1. **Text Assertions**: Verify that specific text is visible on the screen.
2. **Visual Assertions**: Validate the presence of images, icons, or UI elements.
3. **Custom Assertions**: Use descriptive conditions to check for specific outcomes.

***

## How to use the [`assert`](/commands/assert) command

The [`assert`](/commands/assert) command is used to validate conditions during a test. It checks whether the specified expectation is true.

### Syntax:

```yaml theme={null}
- command: assert
  expect: <condition to check>
  async: <true|false> # Optional, defaults to false
```

* **`expect`**: The condition to validate (for example, "The login form is displayed").
* **`async`**: (Optional) If set to `true`, the test will continue running without waiting for the assertion to pass.

***

### Example: Text assertion

#### TestDriver command:

```yaml theme={null}
- command: assert
  expect: The login form is displayed
```

This assertion checks if the login form is visible on the screen.

***

### Example: Async assertion

#### TestDriver command:

```yaml theme={null}
- command: assert
  expect: The success message is displayed
  async: true
```

This assertion runs asynchronously, allowing the test to continue without waiting for the success message to appear.

***

## Visual assertions

Visual assertions validate the presence of images, icons, or UI elements on the screen. These are particularly useful for verifying non-text elements.

### Example: Verifying an image

#### TestDriver command:

```yaml theme={null}
- command: hover-image
  description: Company logo in the top-left corner
  action: hover
```

This command hovers over the company logo to ensure it's present on the screen.

***

### Example: Verifying a button

#### TestDriver command:

```yaml theme={null}
- command: hover-text
  text: Submit
  description: Blue button with the text 'Submit' at the bottom of the form
  action: hover
```

This command hovers over the "Submit" button to confirm its presence.

***

## Combining assertions with other commands

Assertions can be combined with navigation and interaction commands to validate workflows.

### Example: Login workflow with assertions

```yaml login.yaml highlight={12,13, 36, 37} theme={null}
version: 6.0.0
steps:
  - prompt: Open the homepage
    commands:
      - command: hover-text
        text: Login
        description: Login button in the top-right corner
        action: click

  - prompt: Verify the login form is displayed
    commands:
      - command: assert
        expect: The login form is displayed

  - prompt: Enter credentials and submit
    commands:
      - command: hover-text
        text: Email
        description: Email input field
        action: click
      - command: type
        text: user@example.com
      - command: hover-text
        text: Password
        description: Password input field
        action: click
      - command: type
        text: password123
      - command: hover-text
        text: Submit
        description: Submit button
        action: click

  - prompt: Verify the dashboard is displayed
    commands:
      - command: assert
        expect: The dashboard is displayed
```

***

## Debugging assertions

1. **Review Error Messages**:

   * If an assertion fails, TestDriver provides detailed error messages to help identify the issue.

2. **Use Visual Feedback**:

   * Leverage screenshots and visual feedback to verify the state of the application during the assertion.

3. **Refine Descriptions**:
   * Ensure that the `expect` condition or `description` is specific and matches the application's state.

***

## Best practices for assertions

1. **Be Specific**:

   * Use clear and concise conditions for assertions (for example, "The login form is displayed").

2. **Use Visual Assertions for Non-Text Elements**:

   * Validate images, icons, and other UI elements using [`hover-image`](/commands/hover-image) or [`hover-text`](/commands/hover-text).

3. **Combine Assertions with Navigation**:

   * Place assertions after navigation or interaction steps to validate the application's state.

4. **Leverage Async Assertions**:

   * Use `async: true` for non-blocking checks, especially for dynamic content.

5. **Test Incrementally**:
   * Add assertions step-by-step to validate each part of the workflow.

***

By using the [`assert`](/commands/assert) command and visual assertions effectively, you can create robust and reliable tests that ensure your application behaves as expected.