Function toHaveDistanceFrom

toHaveDistanceFrom(
    element: Locator,
    reference: Locator,
    referenceSide: DistanceSide,
    expectedDistanceInPixels: number,
    options?: ToHaveDistanceFromOptions,
): Promise<MatcherReturnType>

Asserts that the target element has a specific distance from another element on a given side.

Top side (side = DistanceSide.Top):

┌───────────────────────┐
|   Reference Element   |
└───────────────────────┘
           ↑
           |  Expected distance = 100px
┌───────────────────────┐
|     Target Element    |
└───────────────────────┘

Bottom side (side = DistanceSide.Bottom):

┌───────────────────────┐
|     Target Element    |
└───────────────────────┘
           |  Expected distance = 100px
           ↓
┌───────────────────────┐
|   Reference Element   |
└───────────────────────┘

Left side (side = DistanceSide.Left):

┌───────────────────────┐             ┌───────────────────────┐
|   Reference Element   | <--100px--> |     Target Element    |
└───────────────────────┘             └───────────────────────┘

Right side (side = DistanceSide.Right):

┌───────────────────────┐             ┌───────────────────────┐
|     Target Element    | <--100px--> |   Reference Element   |
└───────────────────────┘             └───────────────────────┘

Parameters

element: Locator
The element as a Locator to check for distance.
reference: Locator
The reference element to compare against.
referenceSide: DistanceSide
Which side of the reference to measure the distance from.
expectedDistanceInPixels: number
Expected distance in pixels between the elements.
options: ToHaveDistanceFromOptions = {}
Optional distance options.

Returns Promise<MatcherReturnType>

A Promise that resolves with the matcher result.

Example

// Check that element is 100px below reference, allowing 10px of tolerance
await expect(element).toHaveDistanceFrom(reference, DistanceSide.Top, 100, {
  tolerance: 10,
  toleranceUnit: ToleranceUnit.Pixels
});

Example

// Check that element is 200px to the right of reference, with a tolerance of 15px
await expect(element).toHaveDistanceFrom(reference, DistanceSide.Right, 200, {
  tolerance: 15,
  toleranceUnit: ToleranceUnit.Pixels
});