Function toBeWithinViewport

toBeWithinViewport(
element: Locator,
options?: ToBeWithinViewportOptions,
): Promise<MatcherReturnType>

Asserts that the element is fully visible within the current viewport, optionally respecting a safety margin from the viewport edges.

┌────────────────────────────────────┐
│             Viewport               │
│                                    │
│  ┌──marginPixel──┐                 │
│  │               │                 │
│  │   [element]   │ ← must be here  │
│  │               │                 │
│  └───────────────┘                 │
└────────────────────────────────────┘

Parameters

element: Locator
The Locator of the element to check.
options: ToBeWithinViewportOptions = {}
Optional configuration for margin.

Returns Promise<MatcherReturnType>

A Promise that resolves with the matcher result.

Example

// Element must be fully in viewport (no margin)
await expect(card).toBeWithinViewport();

Example

// Element must be fully visible with 50px margin from all edges
await expect(modal).toBeWithinViewport({ marginPixel: 50 });