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

npm install cypress-positional

Usage

1. Register the Plugin

In your cypress.config.ts:

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

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

2. Register Custom Commands

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

import { registerCommands } from 'cypress-positional';

// Register custom commands
registerCommands();

3. Use in Tests

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

Positional Commands

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.

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.

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.

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.

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.

Tasks

The plugin also registers the following Node.js tasks:

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

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

Examples

Testing a Layout

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');
  });
});

Running the Demo

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

# 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

Build

npm run build

Watch Mode

npm run watch

TypeScript Support

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