A Cypress plugin for positional testing - validate element positions (left, right, above, below)
npm install cypress-positionalA 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.
``bash`
npm install cypress-positional
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;
},
},
});
`
In your cypress/support/e2e.ts (or cypress/support/commands.ts):
`typescript
import { registerCommands } from 'cypress-positional';
// Register custom commands
registerCommands();
`
`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');
});
});
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.
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');
`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');
});
});
`
This project includes a demo HTML page and comprehensive test suite:
`bashInstall dependencies
npm install
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
``This plugin includes full TypeScript support with type definitions for all custom commands.