Cypress Positional Plugin

A Cypress plugin that enables you to validate the positional relationships between elements on a page. Assert whether elements are positioned left, right, above, or below each other.

Installation

``bash
npm install cypress-positional
`

Usage

$3

In your cypress.config.ts:

`typescript
import { defineConfig } from 'cypress';
import { cypressPositional } from 'cypress-positional';

export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
cypressPositional(on, config);
return config;
},
},
});
`

$3

In your cypress/support/e2e.ts (or cypress/support/commands.ts):

`typescript
import { registerCommands } from 'cypress-positional';

// Register custom commands
registerCommands();
`

$3

`typescript
describe('Positional Validation', () => {
it('validates element positions', () => {
cy.visit('https://example.com');

// Check if logo is to the left of navigation
cy.get('.logo').isLeftOf('.navigation');

// Check if header is above the main content
cy.get('header').isAbove('main');

// Check if sidebar is to the left of content
cy.get('.sidebar').isLeftOf('.content');

// Check if footer is below the main content
cy.get('footer').isBelow('main');
});
});
`

API

$3

All positional commands are chainable and work with Cypress elements:

#### cy.get(selector).isLeftOf(targetSelector)

Asserts that the element is positioned to the left of the target element.

`typescript
cy.get('#element1').isLeftOf('#element2');
`

The assertion passes when the right edge of the source element is at or before the left edge of the target element.

#### cy.get(selector).isRightOf(targetSelector)

Asserts that the element is positioned to the right of the target element.

`typescript
cy.get('#element1').isRightOf('#element2');
`

The assertion passes when the left edge of the source element is at or after the right edge of the target element.

#### cy.get(selector).isAbove(targetSelector)

Asserts that the element is positioned above the target element.

`typescript
cy.get('#element1').isAbove('#element2');
`

The assertion passes when the bottom edge of the source element is at or before the top edge of the target element.

#### cy.get(selector).isBelow(targetSelector)

Asserts that the element is positioned below the target element.

`typescript
cy.get('#element1').isBelow('#element2');
`

The assertion passes when the top edge of the source element is at or after the bottom edge of the target element.

$3

The plugin also registers the following Node.js tasks:

- log(message: string): Logs a message to the console

`typescript
cy.task('log', 'Task executed from test');
`

Examples

$3

`typescript
describe('Page Layout', () => {
it('validates header layout', () => {
cy.visit('/');

// Logo should be left of navigation
cy.get('.logo').isLeftOf('.nav-menu');

// Both should be in the header which is above main content
cy.get('header').isAbove('main');
});

it('validates sidebar layout', () => {
cy.visit('/dashboard');

// Sidebar on the left
cy.get('.sidebar').isLeftOf('.main-content');

// Footer at the bottom
cy.get('footer').isBelow('.main-content');
});
});
`

$3

This project includes a demo HTML page and comprehensive test suite:

`bash


Install dependencies

npm install

Build the plugin

npm run build

Open Cypress and run the demo test

npx cypress open
`

Then select E2E Testing and run the positional-demo.cy.ts test file to see all positional validations in action.

How It Works

The plugin uses getBoundingClientRect() to get the precise position of elements on the page, then compares their coordinates:

- isLeftOf: Source element's right edge ≤ Target element's left edge
- isRightOf: Source element's left edge ≥ Target element's right edge
- isAbove: Source element's bottom edge ≤ Target element's top edge
- isBelow: Source element's top edge ≥ Target element's bottom edge

All commands log detailed position information to help debug layout issues.

Development

$3

`bash
npm run build
`

$3

`bash
npm run watch
``

TypeScript Support

This plugin includes full TypeScript support with type definitions for all custom commands.