cypress-extender

Extends the functinality of Cypress to ease its usage.

Usage no npm install needed!

<script type="module">
  import cypressExtender from 'https://cdn.skypack.dev/cypress-extender';
</script>

README

cypress-extender

Extends the basic functinality of Cypress (now we can use while/if/for with Cypress)

Why

To combine cypress commands with while/if/for

To make tests short and clear (cy.isVisible(CSS).should('be.false'))

To have less flaky tests (cy.isVisible returns false if the element doesn't exist)

(cy.get(CSS).should('be.visible') fails for element doesn't exist)

Why is it needed

Let's suppose that we have an element that appears ONLY after a specific event

In a usual cy.get approach,

our test will fail (or even worse will be flaky) depending if that event happend/didn't happen before we searched for the element

i.e. open dropdown and wait for inner element to be created there, to identify, it's opened

With Cypress Extender it's possible, in fact we can use an if ccondition, or while loop, to test condition of element

Prerequisites

In order to use this plugin:

  • Cypress must be installed.

Installation

To install the plugin to your project please use:

npm install cypress-extender

in order to also add it to your package.json file so you can use:

npm install --save-prod cypress-extender

Manual

Once Cypress Extender is installed,

there are 2 main options to use this plugin

  • initCypress - adds this plugin's commands to cypress
  • load and use specific function - doesn't change anything in cypress commands

initCypress

in order to load all the extender commands to cypress use:

const { initCypress } = require('cypress-extender');
initCypress();

or alternativly:

import { initCypress } from 'cypress-extender';
initCypress();

in both ways, you'll get many new functions added to cypress, such as:


        cy.exists('body').should('be.true');
        cy.exists('bodyy').should('be.false'); 
        cy.isVisible('body').should('be.true');
        cy.isVisible('bodyy').should('be.false'); 
        cy.hasText('body', 'default blank page').should('be.true');
        cy.hasText('body', 'default blanket page').should('be.false');

and many more options, as you can find below, in this page.

Load required function

If you decide, that you don't want to change anything in cypress commands, however you want to test boolean cases in if statement, or wait for a condition in a while loop, this is probably the better option for you.

in order to load specific function, use:

const { exists } = require('cypress-extender');

or alternativly:

import { exists } from 'cypress-extender';

in both ways you'll be able to test things like:

if (exists('body')) { /* DO SOMETHING */ }
while (exists('body')) { /* DO SOMETHING */ }
for (let i = 0; i <  SOME_MAX_TRIES && exists('body'); i++ ) {
    /* DO SOMETHING */
}

so you'll be able for example to implement something like

const isOpened = () => exists(' SELECTOR THAT APPEARS WHEN OPENED');
const openDropDown = !isOpened() && cy.get('SOME SELECTOR TO OPEN').click();

Also here we support visible in a differnt way, than the usual cy.get('SELECTOR').should('be.visible');

what if, for example you want to wait for element to exist and to be visible, now you can. Simply use something like:

import { isVisible } from 'cypress-extender';
while (isVisible('SELECTOR OF ELEMENT')) {
    /* DO SOMETHING */
}

very simple to use, and should make cypress code much easier to use.

Supported functions

function what is it
exists element should exist, in DOM
isVisible exists in DOM and visible
isCheckbox element exists and is a checkbox
isChecked element exists and is checked
contains element exists and its text contains GIVEN TEXT, this function get 2 arguments cssSelector, text
equals element exists and its text equals to GIVEN TEXT, this function get 2 arguments cssSelector, text(element should be equal to)
isEmpty element exists and has no children
hasNoChildren element exists and has no children
isDisabled element exists and is disabled
isEnabled element exists and is enabled (not disabled)
isFile element exists and is of type file (mostly input[type=file])
isFirstChild element exists and is the first child of its parent element
isFocused element exists and is in focus state
hasSelector element exists and has among its descendants element that matches the css selector
isHeader element exists and is of type header (h1, h2, h5 ...)
isHidden element exists and is hidden
isImage element exists and is of type image
isInput element exists and is of type input
isAnimated element exists and is recognized as running some animation (by JQuery)
isButton element exists and is of type button

Map function

What is map function ?

map function is a simple way to run a callback function

on each element returned from the previous command

and return its results as an array

Use:

        import { initCypressWithMap } from 'cypress-extender';
        initCypressWithMap();

        cy.get('li').map(e => e.text().trim()).then(texts => {
            cy.log('Text are ', texts);
        });

Or any other jquery function combined/not combined with js code.

Log functions

What are log function ?

It is a new way to write text/data to your live report created by Cypress

for example:

If I don't like to search in the entire report scrolling up and down

to find that specific log message that represents what I'm searching for

this is exactly where log messages do that work for me

Use:

        import { INFO } from 'cypress-extender';
        INFO("hi how are you");

Or Use:

        import { initCypressWithLogger } from 'cypress-extender';
        initCypressWithLogger();

        cy.Info("hi how are you");

Which will display a nice INFO line in you report (instead of the old log line).

Such as:

INFO example

Supported log functions

function what is it
Info displays INFO message in the Cypress report
INFO displays INFO message in the Cypress report
Message displays MESSAGE message in the Cypress report
MESSAGE displays MESSAGE message in the Cypress report
Debug displays DEBUG message in the Cypress report
DEBUG displays DEBUG message in the Cypress report
Warn displays WARN message in the Cypress report
WARN displays WARN message in the Cypress report
Custom Allows you to decide what message you want to be printed in the report
CUSTOM Allows you to decide what message you want to be printed in the report

Example to the custom command 


        import { CUSTOM } from 'cypress-extender';
        CUSTOM("YourFuncName", "My data is", someDataObjectOrArray);