Function toBeAbove

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

Asserts that an element is positioned above another element.

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

Strictly above:

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

Touching:

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

Parameters

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

Returns Promise<MatcherReturnType>

A Promise that resolves with the matcher result.

Example

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

Example

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

Example

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