cypress-image-stretch-detector

Detect visually stretched <img> tags in your Cypress tests — fast, simple, and zero-config by default.

What it does? Adds a Cypress command cy.checkImageNotStretched() that verifies an image’s displayed aspect ratio matches its natural aspect ratio.

Why build this package?

Responsive sites resize images via CSS. If a container or rule is slightly off, images get squashed (horizontally or vertically). It looks unprofessional and often slips into production. Visual diff tools can miss this when content changes. This plugin gives you a repeatable, code-level assertion for stretching so you can gate it in CI.

Package Key Features

• 1-line assertion: cy.get('img.selector').checkImageNotStretched()
• Respects object-fit by default (cover/contain/scale-down are not flagged)
• Actionable logging: shows natural vs displayed sizes, ARs, and Δ%
• Works inside Cypress AUT iframe (uses ownerDocument.defaultView)
• TypeScript types with Cypress Chainable augmentation
• Great for single-image smoke checks and layout/template spot checks

How it works (mental model)

1. Waits for image load (avoids naturalWidth = 0).

2. Reads natural size (naturalWidth/naturalHeight) → naturalAR.

3. Reads displayed size (getBoundingClientRect()) → displayedAR.

4. Computes relative aspect delta:

5. If object-fit exists and is not 'fill', the check passes (cropping, not stretching).
   Otherwise, any non-zero Δ is considered stretched. Default threshold = 0.

Why threshold 0?
The default is intentionally strict to catch subtle squashing. (You can make it looser later.)

• remove the below part

How can you integratte with your E2E cypress test/Tiny example (from stretch-test.cy.ts)

/// <reference types="cypress" />

describe('Image stretch detector (single image, threshold = 0)', () => {
  it('checks one car slider image on renty.ae', () => {
    // 1) go to the site you want
    cy.visit('URL');

    // 2) select exactly one <img> and assert
    cy.get('Image className').first().checkImageNotStretched(); // strict, respects object-fit
  });
});

Install & Integration

1) Install the package

If published on npm (recommended):

npm i -D cypress-image-stretch-detector
# or: pnpm add -D cypress-image-stretch-detector

Local development (before publish): choose ONE

A) npm link (fastest while developing)

# in the package folder
npm run build
npm link

# in your Cypress app
npm link cypress-image-stretch-detector

Note: npm link can sometimes cause duplicate deps. If Cypress acts weird, use option B.

B) file: dependency (simple, reliable)

In your Cypress app’s package.json:

{
  "devDependencies": {
    "cypress-image-stretch-detector": "file:../cypress-image-stretch-detector"
  }
}

Then install:

npm i

2) Register the command in Cypress support

Add ONE of the following to your Cypress support file.

Auto-register (just import)
cypress/support/e2e.{js,ts} or cypress/support/commands.{js,ts}:

import 'cypress-image-stretch-detector';

Explicit register (named import)

import { registerImageStretchCommand } from 'cypress-image-stretch-detector';
registerImageStretchCommand();

The plugin augments Cypress.Chainable types automatically (via the package’s bundled index.d.ts), so cy.checkImageNotStretched() is fully typed.