Await-ing Cypress Chains

[vacekj]

Current behavior:

await-ing cypress chains yields undefined

Desired behavior:

await-ing cypress chains yields the value of the chain (since the chain is a promise-like, it should work with await out of the box)

Additional Info (images, stack traces, etc)

I understand the recommended way to use cypress is closures, however, when dealing with multiple variables, we run into callback hell's lil' brother closure hell.

The ability to use await on Cypress chains could be beneficial in many ways:

• avoiding nesting closures many levels deep, thus preventing unreadable code
• making it easy for programmers familiar with traditional async patterns to start using Cypress

Example code using closures

describe('Filter textbox', () => {
    beforeEach(() => {
        cy.get(test("suplovaniTable")).as("suplovaniTable");
        cy.get(test("filterTextbox")).as("filterTextbox");
    });

    it('changes data on filter text change', () => {
        cy.get("@suplovaniTable").then((el) => {
            return el[0].innerHTML;
        }).then((innerHTML) => {
            return sha256(innerHTML);
        }).then((hash) => {
            cy.get("[data-test=suplovaniTable] > tbody > :nth-child(1) > :nth-child(2)")
                .then((tds) => {
                    const text = tds[0].innerText;
                    cy.get("@filterTextbox").type(text);
                    cy.get("@suplovaniTable")
                        .then(el => el[0].innerHTML)
                        .then((innerHTML) => {
                            expect(hash).to.not.equal(sha256(innerHTML));
                        });
                });
        });
    });
});

Example code using await

describe('Filter textbox', () => {
    beforeEach(() => {
        cy.get(test("suplovaniTable")).as("suplovaniTable");
        cy.get(test("filterTextbox")).as("filterTextbox");
    });

    it('changes data on filter text change', async () => {
        const table = await cy.get("@suplovaniTable");
        const hash = sha256(table[0].innerHTML);

        const filterCell = await cy.get("[data-test=suplovaniTable] > tbody > :nth-child(1) > :nth-child(2)");
        await cy.get("@filterTextbox").type(filterCell[0].innerText);

        const newTable = await cy.get("@suplovaniTable");
        const newHash = sha256(newTable[0].innerHTML);
        expect(hash).to.not.equal(newHash);
    });
});

• Operating System: Windows 10 x64
• Cypress Version: Beta 2.1.0
• Browser Version: Chrome 64

[brian-mann]

Cypress commands are not 1:1 Promises.

https://gitter.im/cypress-io/cypress?at=5a9ec8bf458cbde55701c7a8

They have promise like features in the sense that they have a .then(fn) and they can assume other thenables and do the right thing, but they themselves are not true Promises.

This has serious implications where the async/await implementation would simply not work correctly in Cypress.

What is possible - is to use async/await to replace the .then(fn) but even that has problems.

You could not use try / catch because that is the same thing as .catch() for Promises, which Cypress does not and will never have.

Because Cypress enqueues commands on a master singleton, it already manages the async coordination for you. It's impossible to ever lose a chain of commands.

What this means is - you would sometimes add the await keyword when you need to work with the yielded value of a command - but then mostly not do this.

This also means you wouldn't use the async keyword on functions that return Cypress commands.

This IMO would end up being confusing. You would use async/await inconsistently from how you'd use it outside of Cypress. It would require a lot of explanation in the docs.

FWIW you can already avoid callback hell in Cypress by writing much more terse JS. There is almost never a situation where you ever would need to create nested callbacks, or ever need to make heavy use of const.

describe('Filter textbox', () => {
  beforeEach(() => {
    cy
    .get(test('suplovaniTable')).as('suplovaniTable')
    .invoke('html')
    .then(sha256)
    .as('hash')

    cy.get(test('filterTextbox')).as('filterTextbox')
  })

  it('changes data on filter text change', () => {
    cy
    .get('@suplovaniTable')
    .find('tbody > :nth-child(1) > :nth-child(2)')
    .invoke('text')
    .then((text) => {
      cy.get('@filterTextbox').type(text)
    })

    cy
    .get('@suplovaniTable')
    .invoke('html')
    .should(function ($html) {
      expect(this.hash).to.not.equal(sha256($html))
    })
  })
})

[danielkcz]

It's a lot about a mindset. Being a freshman at Cypress and using async/await almost everywhere now it's tough getting used to the different paradigm for an async code.

Seeing this explanation now (and some discussion on gitter) I think it makes total sense not to support async/await. Might be worth to link this issue in docs as I believe many people will be asking for it, especially when seeing examples with .then can give a false impression that it's a great candidate for async/await.

---

Just to be clear from that last example. Why is there .then and .should acting like it's the same thing? I mean both are accepting callback and getting a value of the chain. I suppose that the major difference is that .should will retry till callback passes (or timeouts)? Using .then instead would work only if assertion would pass on the first run. Is that correct?

    cy
    .get('@suplovaniTable')
    .invoke('html')
    .then(function ($html) {
      expect(this.hash).to.not.equal(sha256($html))
    })

PS: I think there is a small mistake of using function instead of fatarrow as this.hash won't be available? Unless all callbacks are bound to test context internally?

[NicholasBoll]

PS: I think there is a small mistake of using function instead of fatarrow as this.hash won't be available? Unless all callbacks are bound to test context internally?

Yes. Mocha does this as well (as does jQuery). Much of the time it doesn't matter since people use closures instead of this.

You can see it here: https://github.com/cypress-io/cypress/blob/develop/packages/driver/src/cy/commands/connectors.coffee#L350. The type definitions also indicate the context is changed (although there isn't a good way to know what's on that context since interfaces cannot be mutated by a runtime)

[brian-mann]

I will open a new issue for adding a cy.alias function to avoid the use of this. I don't use this anymore in any of my code, and with fat arrow functions it'll never point to the right context anyway.

We can make cy.alias smart to point out that if you call it before an alias is defined, that it will throw a nice error explaining what you're doing wrong.

This would allow you to replace the: this.hash with cy.alias('hash') which would return a synchronous value.

[brian-mann]

@FredyC .then() and .should() are not the same thing. They're completely different. That's the difference - they both accept a callback function but otherwise are completely dissimilar.

Using .should() retries which insulates you from having to know the precise moment the state has settled. You can simply "describe" what you want, and Cypress will retry until it matches.

Read what I'm writing below - and then apply that to both of the cases of using .then(). Both of these uses can possibly lead to non-deterministic results that will fail your tests.

---

To be clear - it possible to use async/await in Cypress anytime you would otherwise use .then(fn).

However - with that said, using .then() frequently enough to need this is generally a sign of an anti pattern.

In every use case of .then() we are "locking" ourselves into something that may or may not give us a guarantee of the correct value. The whole reason we're even using .then() is to make our tests "dynamic" - but abuse of that can quickly lead to non determinism.

The root cause of the problem is documented here: https://docs.cypress.io/guides/core-concepts/conditional-testing.html#

Whenever you use a .then() if you've provided no assertions then there is no guarantees its value is even correct.

For instance you're typing text after yielding. What is the guarantee that text is correct? What if it hasn't rendered yet? What if its about to change? You'd need to add an assertion before yielding text. And if you can add an assertion about its state then you already know what the value is, and don't need to yield it.

Of course, this isn't always the case, if you're using vanilla javascript or jQuery, then you can be sure things have rendered synchronously. But try this with modern frameworks and you'll potentially be digging yourself a hole that's tough to debug.

The key to determinism is already knowing the desired result ahead of time. When that is known, you don't need to yield dynamic values - because they're not dynamic, they're static. Doing that will avoid even the need for yielding values from the DOM.

[NicholasBoll]

@brian-mann with cy.alias, the following would be possible, correct?

cy
  .get('@suplovaniTable')
  .invoke('html')
  .then(sha256)
  .should('not.equal', cy.alias('hash')))

[brian-mann]

Yes but only if its been evaluated already. It won't make anything easier - it's just a simple replacement for this and we can make it smart and throw when you attempt to use aliases which haven't been defined yet - as opposed to just returning undefined.

// nope, same problem
cy.wrap('foo').as('f')
cy.wrap('foo').should('eq', cy.alias('f')) // alias is not defined yet

// yup, works
cy.wrap('foo').as('f').then((str) => {
  expect(str).to.eq(cy.alias('f'))
})

[NicholasBoll]

Ah. In your example above, the .as('hash') is in the beforeEach, so it has been evaluated. That might still be a bit tricky to know when things have been evaluated.

cy.alias would have the benefit of being able to give a warning/error with a link to the documentation about this caveat. You can track the setting of items on the internal state object and issue a warning or error about cy.alias being used on a property that hasn't been set yet. A link to documentation about this in the message would help.

[NicholasBoll]

The following example shows the limitations of using async/await in a Cypress test:

it('should work?', async () => {
  const body1 = await cy.get('body')
  const body2 = await cy.get('body')
  cy.get('body').then(body => console.log('body', body)) // logs jQuery-wrapped body tag

  // "promises" have resolved by this point
  console.log('body1', body1) // logs jQuery-wrapped body tag
  console.log('body2', body2) // logs undefined
})

it('should work?', async () => {
  const [body1, body2] = await Promise.all([
    cy.get('body').toPromise(),
    cy.get('body').toPromise(),
  ])

  // "promises" have resolved by this point
  console.log('body1', body1) // logs jQuery-wrapped body tag
  console.log('body2', body2) // logs jQuery-wrapped body tag
})

I agree it is a bit strange especially with the prominence of async/await

I think it is best to think about Cypress commands as streams or pipelines with .then as a way to unwrap (or compose). cy.get is a common entry to this stream of data (Cypress calls them subjects). Some Cypress commands mutate DOM state (.type()), some transform the subject (.its()), but almost all return a subject for the next command in the stream. When you're done with that stream, alias it if you need it later.

[danielkcz]

@NicholasBoll I am curious why did you call .toPromise() in a second example? I don't even know where that API came from, don't see anywhere else. However, what happens if you do it the first example as well?

If this really is not working, then there should be some big red warning in docs about using async/await as it can only lead to headaches.

Although it's really hard to understand why is it actually different. I mean await uses .then under the hood, so why it wouldn't be able to get the value out of it? There is definitely something fishy about it.

[danielkcz]

On the other hand, I could imagine doing something like this.

cy.get('body').then(async ($body) => {
  const first = await doSomethingAsyncWithBody($body)
  const second = await doSomethingElseAsync(first)
  ...etc
}).alias('result')

In this case, it makes a great sense to have async/await available otherwise it would become callback hell once again. Yea sure, it can be considered edge case, but it can happen.

[brian-mann]

@FredyC due to the functional nature of Promises even this I disagree with. Having callback hell is always a sign of poor design.

async/await is the imperative form of Promises.

You could just as easily write it this way...

cy
.get('body')
.then(doSomethingAsyncWithBody)
.then(doSomethingElseAsync)
.as('result')

[NicholasBoll]

Oops, I didn't mean to leave .toPromise() in the example. I was attempting to find out how the subject was passed around and why the promise gets lost. Commands continue to get enqueued. The presence of toPromise() makes no difference.

I'm using Typescript and Promise.all doesn't consider a Cypress chainer to be a valid promise type even though it works at runtime. I did a custom command that returns a real Promise to make Promise.all happy.