Proposal: Add a group to commands for nicer command logging

[NicholasBoll]

I've been playing around with ways of defining reusable helpers (blog post coming) and have been using the Cypress log API and passing { log: false } to allow control of the log output of these helpers/commands. This has been useful, but there are some times that I want to dive into that abstraction (most likely on failure) to see what step of the helper failed.

I think a concept of a group would be useful here. Instead of passing { log: false } to every encapsulated command, having a group would help a lot more

Current behavior:

// This will work on https://github.com/cypress-io/cypress-example-todomvc
export const createTodo = (name) => {
  const log = Cypress.log({
    name: 'createTodo',
    message: name,
    consoleProps() {
      return {
        'Inserted Todo': name,
      }
    }
  })
  cy.get('.new-todo', { log: false }).type(`${name}{enter}`, { log: false })

  return cy
    .get('.todo-list li', { log: false })
    .contains('li', name.trim(), { log: false })
    .then(($el) => {
      log.set({ $el }).snapshot().end()
    })
}

// to use this helper:
createTodo('Learn the Cypress Log API')
  .then(console.log) // logs the created todo element from the TodoMVC Cypress example

Screenshot of the above:

Proposed behavior:

export const createTodo = (name) => {
  const group = Cypress.group({
    name: 'createTodo',
    message: name,
    consoleProps() {
      return {
        'Inserted Todo': name,
      }
    }
  })

  cy.get('.new-todo').type(`${name}{enter}`)

  return cy
    .get('.todo-list')
    .contains('li', name.trim())
    .then($el => { group.set({ $el }).snapshot().end() })

Matching the log API seems like a logical choice. In the UI it would show createTodo with the logging the same as the Current behavior example, but would have an arrow that would expand to the grouped commands. This would both simplify creating custom command output (don't have to pass { log: false } to everything) as well as make it easier to understand that's going on under the hood of a custom command. The group would be collapsed by default and expanded if a nested command failed.

[NicholasBoll]

This proposal is conceptually similar to the Web Console log's group: https://developer.mozilla.org/en-US/docs/Web/API/Console/group

[kamituel]

I'm surprised this didn't get more votes yet.

I'd love to be able to group several commands into one, nicely labelled, group that is collapsed by default, and autoxpands on a failure.

Also note this could be useful when having a larger test (which we are encouraged to do) to group sections of a single test case for better readability.

[NicholasBoll]

I was thinking about this more. Basically as test suites get larger, people look to ways to "macro" commands. There are a few ways to do this:

1. Cypress Custom Commands

// definition
Cypress.Commands.add('fillForm', (first, last) => {
  cy.get('#first').type(first)
  cy.get('#last').type(last)
}

// usage
cy.fillForm('John', 'Doe')

// log
GET  #first
TYPE John
GET  #last
TYPE Doe

2. Regular functions

// definition
function fillForm(first, last) {
  cy.get('#first').type(first)
  cy.get('#last').type(last)
}

// usage
fillForm('John', 'Doe')

// log
GET  #first
TYPE John
GET  #last
TYPE Doe

3. Functional composition (.then)

// definition
const fillForm = (first, last) => ($form) => {
  cy.wrap($form).find('#first').type(first)
  cy.wrap($form).find('#last').type(last)
}

// usage
cy
  .get('#form')
  .then(fillForm('John', 'Doe'))

// log
GET  #form
THEN
WRAP <form>
FIND #first
TYPE John
WRAP <form>
FIND #first
TYPE Doe

4. Functional composition (.pipe)

// definition
const fillForm = (first, last) => function fillForm($form) {
  cy.wrap($form).find('#first').type(first)
  cy.wrap($form).find('#last').type(last)
}

// usage (.pipe)
cy
  .get('#form')
  .pipe(fillForm('John', 'Doe'))

// log (.pipe)
GET  #form
PIPE fillForm
WRAP <form>
FIND #first
TYPE John
WRAP <form>
FIND #first
TYPE Doe

5. Page Objects

// definitions
class Page {
  fillForm(first, last) {
    cy.get('#first').type(first)
    cy.get('#last').type(last)
  }
}

// usage
const page = new Page()

page.fillForm('John', 'Doe')

// log
GET  #first
TYPE John
GET  #last
TYPE Doe

The function name fillForm isn't shown in the log output of all the examples except cypress-pipe. Even cypress-pipe is confusing, because I only see cy.get('#form').pipe(fillForm('John', 'Doe')) in my test, but a bunch more commands logged in the Command Log. Grouping would make this much easier to understand the relationship between my test code and the log.

The following could be modifications to get grouping to work:

1. Cypress Custom Commands

// definition
Cypress.Commands.add('fillForm', (first, last) => {
  cy.group('fillForm', () => {
    cy.get('#first').type(first)
    cy.get('#last').type(last)
  })
}

// usage
cy.fillForm('John', 'Doe')

// log
GROUP fillForm
  - GET  #first
  - TYPE John
  - GET  #last
  - TYPE Doe

2. Regular functions

// definition
import { group } from '@cypress/group' // Higher-order function/class decorator

const fillForm = group('fillForm', (first, last) => {
  cy.get('#first').type(first)
  cy.get('#last').type(last)
})

// usage
fillForm('John', 'Doe')

// log
GROUP fillForm
  - GET  #first
  - TYPE John
  - GET  #last
  - TYPE Doe

3. Functional composition (.then)

// definition
const fillForm = (first, last) => ($form) => {
  cy.group('fillForm', () => {
    cy.wrap($form).find('#first').type(first)
    cy.wrap($form).find('#last').type(last)
  })
}

// usage
cy
  .get('#form')
  .then(fillForm('John', 'Doe'))

// log
GET  #form
THEN
GROUP fillForm
  - WRAP <form>
  - FIND #first
  - TYPE John
  - WRAP <form>
  - FIND #first
  - TYPE Doe

4. Functional composition (.pipe) (no changes actually needed)

// definition
const fillForm = (first, last) => function fillForm($form) {
  cy.wrap($form).find('#first').type(first)
  cy.wrap($form).find('#last').type(last)
}

// usage
cy
  .get('#form')
  .pipe(fillForm('John', 'Doe'))

// log
GET  #form
PIPE fillForm
  - WRAP <form>
  - FIND #first
  - TYPE John
  - WRAP <form>
  - FIND #first
  - TYPE Doe

5. Page Objects

// definitions
import { group } from '@cypress/group' // Higher-order function/class decorator
class Page {
  @group('fillForm') // optional if name can't be inferred
  fillForm(first, last) {
    cy.get('#first').type(first)
    cy.get('#last').type(last)
  }
}

// usage
const page = new Page()

page.fillForm('John', 'Doe')

// log
GROUP fillForm
  - GET  #first
  - TYPE John
  - GET  #last
  - TYPE Doe

[NicholasBoll]

I spent some time looking into this over the weekend. I don't think group can be added without changes to the Cypress runner code. The React UI renders a list, but will need to render a tree. cy.within would be easier to understand as well in the Command Log if it also created a group. Right now you can understand what is inside a cy.within while debugging by clicking on Commands inside a within by the debug output, but not part of the Video or screenshots.

Next step would be to evaluate how much code needs to change to support grouping. cy.within required changes to all commands within querying.coffee to know if querying APIs should target the root element or the withinSubject. Grouping doesn't seem to need that level of interaction with other commands, but does require cooperation with the UI.