fix: explain combining assertions (#30)

* add AND OR assertion callback functions spec

* add callback function to the README

* document combining assertions

README.md

@@ -61,6 +61,38 @@ You can use assertions with `not`
 cy.get('#enrolled').if('not.checked').check()
 ```
 
+### Callback function
+
+You can check the value yourself by writing a callback function, similar to the [should(callback)](http://on.cypress.io/should#Function) and its [many examples](https://glebbahmutov.com/cypress-examples/commands/assertions.html). You can use predicate and Chai assertions, but you **cannot use any Cypress commands inside the callback**, since it only synchronously checks the given value.
+
+```js
+// predicate function returning a boolean
+const isEven = (n) => n % 2 === 0
+cy.wrap(42).if(isEven).log('even').else().log('odd')
+// a function using Chai assertions
+const is42 = (n) => expect(n).to.equal(42)
+cy.wrap(42).if(is42).log('42!').else().log('some other number')
+```
+
+For more examples, see the [cypress/e2e/callback.cy.js](./cypress/e2e/callback.cy.js) spec
+
+### Combining assertions
+
+If you want to right complex assertions that combine other checks using AND, OR connectors, please use a callback function.
+
+```js
+// AND predicate using &&
+cy.wrap(42).if((n) => n > 20 && n < 50)
+// AND connector using Chai "and" connector
+cy.wrap(42).if((n) => expect(n).to.be.greaterThan(20).and.to.be.lessThan(50))
+// OR predicate using ||
+cy.wrap(42).if((n) => n > 20 || n < 10)
+```
+
+Unfortunately, there is no Chai OR connector.
+
+For more examples, see the [cypress/e2e/and-or.cy.js](./cypress/e2e/and-or.cy.js) spec file
+
 ## else command
 
 You can chain `.else()` command that is only executed if the `.if()` is skipped.

cypress/e2e/and-or.cy.js

@@ -0,0 +1,86 @@
+/// <reference types="cypress" />
+// @ts-check
+
+import '../../src'
+
+describe('AND assertions', () => {
+  context('uses && inside the predicate callback', () => {
+    it('T && T', () => {
+      cy.wrap(42)
+        .if((n) => n > 20 && n < 50)
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@if').should('have.been.called')
+      cy.get('@else').should('not.have.been.called')
+    })
+
+    it('T && F', () => {
+      cy.wrap(42)
+        .if((n) => n > 20 && n < 40)
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@else').should('have.been.called')
+      cy.get('@if').should('not.have.been.called')
+    })
+  })
+
+  context('uses Chai assertions', () => {
+    it('ok and ok', () => {
+      cy.wrap(42)
+        .if((n) => expect(n).to.be.greaterThan(20).and.to.be.lessThan(50))
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@if').should('have.been.called')
+      cy.get('@else').should('not.have.been.called')
+    })
+
+    it('ok and not ok', () => {
+      cy.wrap(42)
+        .if((n) => expect(n).to.be.greaterThan(20).and.to.be.lessThan(40))
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@else').should('have.been.called')
+      cy.get('@if').should('not.have.been.called')
+    })
+  })
+})
+
+describe('OR assertions', () => {
+  context('uses || inside the predicate callback', () => {
+    it('T || F', () => {
+      cy.wrap(42)
+        .if((n) => n > 20 || n < 10)
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@if').should('have.been.called')
+      cy.get('@else').should('not.have.been.called')
+    })
+
+    it('F || T', () => {
+      cy.wrap(42)
+        .if((n) => n > 200 || n < 50)
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@if').should('have.been.called')
+      cy.get('@else').should('not.have.been.called')
+    })
+
+    it('F || F', () => {
+      cy.wrap(42)
+        .if((n) => n > 200 || n < -40)
+        .then(cy.spy().as('if'))
+        .else()
+        .then(cy.spy().as('else'))
+      cy.get('@else').should('have.been.called')
+      cy.get('@if').should('not.have.been.called')
+    })
+  })
+
+  // note that we cannot easily do OR using Chai assertions
+})