How can I define a custom assertion operator in Cypress?

In Cypress, defining custom assertions requires using Cypress's plugin system. You can extend the Chai assertion library to add custom assertion methods. Below, I will detail the steps and examples for defining a custom assertion.

Step 1: Create a Custom Assertion Function

First, create an assertion function that executes the actual assertion logic. Let's define an assertion method beInRange to check if a number falls within a specified range:

javascript
function beInRange(value, range) {
  return value >= range[0] && value <= range[1];
}

Step 2: Extend the Chai Assertion Library

Next, within your Cypress test files or dedicated support files, extend the Chai assertion library to add your custom assertion method:

javascript
Cypress.Commands.add("chai", () => {
  chai.Assertion.addMethod('beInRange', function (range) {
    const subject = this._obj;

    // Apply the assertion logic
    this.assert(
      beInRange(subject, range),
      'expected #{this} to be in range #{exp}',
      'expected #{this} not to be in range #{exp}',
      range
    );
  });
});

Step 3: Use the Custom Assertion

Now that your custom assertion beInRange is defined, you can use it directly in your test cases:

javascript
describe('Number range test', () => {
  it('5 should be between 1 and 10', () => {
    expect(5).to.beInRange([1, 10]);
  });
});

Example Explanation

In this example, the beInRange custom assertion checks if a number falls within a specific range. We first define a basic assertion logic function beInRange, then extend the Chai assertion library to add it as a method. Finally, in the test case, we use the expect statement to invoke this custom assertion.

This approach makes your test cases clearer and easier to maintain, while also aligning assertions more closely with business logic and reader intuition.