Improve invoking native DOM methods

[loilo]

Current behavior:

Cypress makes invoking methods on native DOM elements less expressive than it could be.

My use case: I want to call an <input>'s checkValidity method. According to the FAQ I basically need to do this:

cy.get('input')
  .should($input => {
    expect($input.get(0).checkValidity()).not.to.equal(false)
  })

This basically works, but Cypress' otherwise amazing expressivity takes a hard hit here since the logs naturally don't know anything about the invocation:

→ The assertion is shown, however the desired behaviour would be to also have the invocation listed in the log, as it does when running .invoke().

Desired behavior:

I'd like to advocate for a built-in way to invoke native DOM methods. Some quick thinking lead me to two possible solutions:

The obvious one. Provide an .invokeNative() method on the Cypress wrapper. However having two methods for basically the same thing may not be desirable.

The embracing-jQuery one. Extend the built-in jQuery copy with a native method that proxies native DOM calls. I've tried this myself, but you apparently have shielded the Cypress.$.fn away from curious developers. 🙃

The implementation would basically be this:

Cypress.$.fn.native = (method, ...args) => {
  return this.get(0)[method](...args)
}

which would allow to invoke native DOM functionality as easy as:

cy.get('input')
  .invoke('native', 'checkValidity')
  .should('not.equal', false)

I'd love to hear your feedback on this.

• Operating System: macOS 10.12.6
• Cypress Version: Beta 1.0.2
• Browser Version: Chrome 61

[brian-mann]

Yah this is something I've thought about.

We have some internal notes in the driver about exposing a new configuration like:

{ wrapDomElementsWithJQuery: false }

This would then prevent Cypress from ever wrapping any DOM elements it encounters in jquery - and instead pass everything along. Our internal command signatures would not change (they'd have to accommodate both object types) but when yielding the elements you'd need to update your code.

However I think this doesn't really solve your problem - it seems you probably want to keep the wrapping of jquery, but be able to lean into the native elements when you want to.

The problem is that Cypress will continually re-wrap DOM elements whenever they are returned as the subject of a command. This is to ensure that internally Cypress always understands the type. It even converts jquery objects from your application back into our own. That's the only way we can control them deterministically.

If we didn't do that you could write this code:

cy.get('element').invoke('get', 0).invoke('checkValidity')

The problem is that invoke('get', 0) will unroll the native DOM element but then it'll be wrapped back up when the next invoke runs.

I think currently it's not really that big of a deal to utilize a then or should to explicitly call what you're trying to do.

You cite that the command log is the problem here - that you cannot easily tell because its comparing booleans instead of objects. That would still be the case here with my example above. Chaining the should to the invoke('checkValidity') would still change the subject to be boolean and not DOM. So that wouldn't really help you.

Even in its current state the Command Log does in fact help provide visual reference for the assertion. Notice how the assertion is indented? It knows that the assertion is about the current subject: the <input>.

My final thought is that if you did want to assert in regards to something about the element then you'd need to add a chai assertion plugin. Something like `cy.get('input').should('be.valid'). You would then make that assertion do the right thing and could call whatever methods you like but keep the subject as the element reference.

That's exactly what we've done for all DOM based assertions here:

https://github.com/cypress-io/cypress/blob/develop/packages/driver/src/cypress/chai_jquery.coffee

You'll notice it takes a bit of work to be able to display the subject and yet assert on another property or value. Don't think there's any way to avoid that.

P.S. you could just make your own custom command: https://docs.cypress.io/api/cypress-api/custom-commands.html

[loilo]

Thanks for going into such detail on this!

The problem is that Cypress will continually re-wrap DOM elements [...]

Yeah, I've kind of noticed by trial & error, similar to the snippet you mentioned — so now I also know why it fails.

comparing booleans instead of objects [...] would still be the case here

Sure, it always comes down to an expected true to not equal false. What I'm missing is the INVOKE log that appears on the "standard" jQuery invocations.

you could just make your own custom command

That's the path I took after creating the issue. I registered a cy.invokeNative() command that will first cy.log() the method call similarly to the built-in invoke and then return the result of the method call.

It's not perfect:

• The cy.log() naturally says LOG on the left instead of something like DOM-INVOKE which wastes some precious horizontal space that could be taken by the method signature.
• It creates an additional WRAP log item.

...but it's much better than the.get(...).should(...) approach.

Something like cy.get('input').should('be.valid').

I like the idea of a Chai plugin, for my case it sounds pretty clean to me.

That said, I still find it a little bit quirky that those kinds of detours are needed to get a simple DOM method call to work – which will probably become even more common with the eventual rise of web components.

[brian-mann]

You would use the Cypress.log API to control what is logged at a more fine grained level than cy.log. You could also turn off wrap from logging cy.wrap(..., { log: false }).

I'll keep thinking about this.

[loilo]

Thanks, that's really helpful!

I had not yet found out about Cypress.log, only had read the cy.log() docs page — maybe a cross-reference in its See also section could be useful to others. :)

[brian-mann]

It's not documented much / at all.

If you look at the driver source code (look at any command) you'll see how it's used. That's how you can control everything. The built in Cypress commands use the same interface you have access to.

[loilo]

Yep, your hints took me to a point where I'm pretty satisfied with the resulting command:

Thanks for the gentle introduction!

For the record, here's the source of my invokeDom command:

Cypress.Commands.add(
  'invokeDom',
  { prevSubject: [ 'element', 'document', 'window' ] },
  (subject, method, ...args) => {

  // Arguments string generator
  // Aligns with stringified arguments of Cypress' `invoke()`
  function stringifyArg (arg) {
    if (typeof arg === 'function') {
      return 'function(){}'
    } else if (Array.isArray(arg)) {
      return `[${arg.map(stringifyArg).join(', ')}]`
    } else if (typeof arg === 'object') {
      return `{${Object.keys(arg)
        .map(key => `${key}: ${stringifyArg(arg[key])}`)
        .join(', ')}}`
    } else {
      return String(arg)
    }
  }

  // Return value of the method call to be logged
  const result = subject.get(0)[method](...args)

  // Stringified representation of the method call
  const signature = `.${method}(${args.map(stringifyArg).join(', ')})`

  Cypress.log({
    $el: subject,
    displayName: 'invoke-dom',
    message: signature,
    consoleProps () {
      return {
        'Function': signature,
        'With Arguments': args.length
          ? args
          : undefined,
        'On': subject.get(0),
        'Yielded': result
      }
    }
  })

  return cy.wrap(result, { log: false })
})

[brian-mann]

This is a pretty good start.

Couple things...

There are a bunch of built in stringifier functions in Cypress.

They do slightly different things and are used in a bunch of places in the driver...

Cypress.utils.stringify(...)
Cypress.utils.stringifyArg(...)
Cypress.utils.stringifyActual(...)

The bigger problem with your custom command is that based on the way you've written this you've made it mostly impossible to retry assertions until they pass.

Why?

Well in the built in Cypress commands - each command has to decide how and if it should retry, and of course whether it has any built in default assertions.

There is an API for this but it has not been documented nor 100% formalized.

By returning the cy.wrap command at the very end - you're then passing off the result value to cy.wrap which then ends up utilizing the retry code built into that command.

That means that your assertions are actually chained to the cy.wrap and it will retry them until the pass.

The problem is that once you pass off an immutable value like a Boolean then retrying becomes worthless.

cy.wrap could not possibly do anything because its just been handed a value - it has no idea where it came from or anything.

I actually cannot think of a way to make this work using what you have available at the moment. We likely need to bite the bullet and document the retry API's.

[brian-mann]

Today I would just recommend looking at the driver code to see how invoke or wrap is created and then using those API's. We wrote them to be publicly available. You'll then have to implement your own retry logic. It's not that hard but you'll have to do some legwork.

[loilo]

Sounds good to me so far — thanks again for putting in the time for feedback & help! 👍

[anupadas]

Uncaught TypeError: Cannot read property 'getBoundingClientRect' of null This error originated from your application code, not from Cypress. When Cypress detects uncaught errors originating from your application it will automatically fail the current test. This behavior is configurable, and you can choose to turn this off by listening to the 'uncaught:exception' event. https://on.cypress.io/uncaught-exception-from-application
Can you help me on mention error what can I do in this .not able to fix this.

[jennifer-shehane]

@anupadas The error you are getting originated from your application code, not from Cypress. Look for uses of getBoundingClientRect in your application's code or a 3rd party. If you want to ignore the error, add this to your test file

Cypress.on('uncaught:exception', (err, runnable) => {
  return false
})