Function toBeBelow

toBeBelow(
    element: Locator,
    reference: Locator,
    options?: Tolerance,
): Promise<MatcherReturnType>

Asserts that an element is positioned below another element.

The element passes if its top edge is at or below the bottom edge of the reference, within the specified tolerance.

Strictly below:

┌───────────────┐
│   reference   │
└───────────────┘
        |
        ↓
┌───────────────┐
│    element    │
└───────────────┘

Touching:

┌───────────────┐
│   reference   │
└───────────────┘
┌───────────────┐
│    element    │
└───────────────┘

Parameters

element: Locator
The element as a Locator that should be below.
reference: Locator
The element as a Locator that should be above.
options: Tolerance = {}
Optional alignment options.

Returns Promise<MatcherReturnType>

A Promise that resolves with the matcher result.

Example

// Element is strictly below reference (no overlap, no tolerance)
await expect(content).toBeBelow(header);

Example

// Element can overlap reference by up to 10px
await expect(subtitle).toBeBelow(title, { tolerance: 10, toleranceUnit: ToleranceUnit.Pixels });

Example

// Element can overlap reference by up to 5% of reference height
await expect(text).toBeBelow(icon, {
  tolerance: 5,
  toleranceUnit: ToleranceUnit.Percent
});