Add options to customize name and displayName and message of some builtin commands

[DanaGoyette]

What would you like?

A way to customize the name and displayName and message attributes of some built-in commands, such as cy.get and .find.

Why is this needed?

This can help unclutter the command log, by moving the "key" of what it's looking for from the message to the displayName.

This could also be useful to partially address another feature request, by giving a way to tidy up the logging without disabling it entirely: #8296

I've tried doing it with a custom command, but custom commands that wrap cy commands aren't able to fully replicate the logging:

• Can't highlight element by setting $el, especially in cases where you expect it not to exist
• Can't call a callback each time the selector result is checked (.then only happens after element exists, and .should breaks default assertions)
• Can't call a callback when the chained assertions fail (need something like .onFail: it would be block-scoped, and would allow logging, but not allow canceling the failure)
• Can't use verifyUpcomingAssertions on the return value of .get (because that mixes synchronous and asynchronous code)
• Can't use verifyUpcomingAssertions in a .should block (because it causes an infinite loop)

As an experiment, I managed to get something like what I want by copying the code of the .get() method, but that's too messy, and all the shadowDom stuff seemed not to be publicly exposed.

[DanaGoyette]

A hackish approach I found to work for get is to pass the undocumented _log attribute, but I'd like something more official than that. It also doesn't work for the find method.

cypress/packages/driver/src/cy/commands/querying.js

Line 100 in 0f6d7bd

if (options._log == null) {

I'm not sure whether it would be better to add the name and message to options directly, or to make it accept a LogConfig object (and have it override consoleProps).

My current approach looks something like this:

export function getByTestId<E extends HTMLElement>(
  testId: string,
  options?: Partial<Existable & Cypress.Loggable & Cypress.Timeoutable & Cypress.Withinable & Cypress.Shadow>
): Cypress.Chainable<JQuery<E>> {
  const selector = `[data-testid=${testId}]`
  const userOptions = options || {}

  let mustExist: boolean = userOptions.exists ?? true
  delete userOptions.exists

  options = Cypress._.defaults({}, userOptions, {
    exists: true,
    log: true,
    timeout: Cypress.config('defaultCommandTimeout'),
  })

  const consoleProps = {
    Selector: selector,
    Yielded: undefined,
    Elements: undefined,
  }

  const logConf: Partial<Cypress.LogConfig> = {
    name: 'Get Element by Data-TestID',
    displayName: 'get(testid)',
    message: testId,
    timeout: options.timeout,
    //consoleProps: () => consoleProps
    // @ts-ignore (undocumented attribute)
    type: 'parent', // no '-' in command log
    // @ts-ignore (undocumented attribute)
    autoEnd: false,
  }

  const log = options?.log ? Cypress.log(logConf) : null
  options['_log'] = log
  return cy
    .get<E>(selector, { ...options })
    .should((currentSubject: JQuery<E>) => {
      log?.set('$el', currentSubject)
      Cypress._.extend(logConf, { $el: currentSubject })
      Cypress._.extend(consoleProps, {
        Selector: selector,
        Yielded: currentSubject ? Cypress.dom.getElements(currentSubject) : '--nothing--',
        Elements: currentSubject ? currentSubject.length : undefined,
      })
      if (mustExist) {
        expect(currentSubject).to.exist
      } else {
        expect(currentSubject).to.not.exist
      }
      log?.snapshot()
      log?.end()
    })
}

[DanaGoyette]

In my own uses I ended up just switching back to native cy.get and relying on quotes around the ID for emphasis. This is enough to satisfy my needs for now, and I'll revisit this eventually.

For reference, I ended up making a far simpler helper method:

const byTestId = (testId: string) => `[data-testid="${testId}"]`

Used as follows:

cy.get(byTestId('some-test-id'))

Cypress command log comparison, showing how quotes help:

get  |  [data-testid=some-test-id]
get  |  [data-testid="some-test-id"]

(I also tried using getByTestId from testing-library/cypress, but that has quirks with logging and chaining.)

[jennifer-shehane]

Since this hasn’t gotten a lot of interest over the years, we’ll close this issue.