In Cypress, what does the Command Log show when a custom command runs?

## The Command Log logs commands, not helpers Every built-in Cypress command writes its own entry. `cy.get()`, `.click()`, `cy.request()` and the rest each call `Cypress.log()` from inside their implementation, which is why they appear as named rows in the Command Log with a subject, a duration and a snapshot. `Cypress.Commands.add()` adds nothing of the kind. It stores your function under a name and installs it on the `cy` chain; the function itself is not a logged step. So when a spec calls ```js cy.approveReport('exp-4417') ``` and the command body runs `cy.get()`, `.click()` and `cy.request()`, the Command Log contains three rows — `get`, `click`, `request` — sitting at the same level as commands typed directly in the spec, with no row named `approveReport` and no grouping around them. The Command Log has no idea the custom command exists. That is the opposite of what most people expect, and it is the surface cost this abstraction carries. ## Three ways the same steps read | How you wrote it | What the Command Log shows | |---|---| | Inline in the spec | `get`, `click`, `request` — and the spec line is the code frame | | Inside a custom command | the same `get`, `click`, `request` — nothing names the command | | Custom command with `{ log: false }` inside | only whatever the command logs deliberately; the chain is hidden | The third row is the standard cleanup: pass `{ log: false }` to the inner commands and emit a single entry of your own, which is what Cypress's own guidance recommends when a command issues many internal commands. It buys a tidy log and pays for it by hiding the chain that actually ran. Neither default nor cleanup gives you both. ## Where the failure gets reported When a command inside the body fails, the error attaches to **that inner command's** log entry — the `click` row, not an `approveReport` row, because there is no `approveReport` row. Two things follow: - **The code frame points into the definition.** The failing line Cypress opens is the one inside `cypress/support/commands.js`, not the `cy.approveReport('exp-4417')` line you wrote. The spec line is further down the stack. - **The log reads as if the spec did it.** A reviewer skimming the log sees a `click` on a selector that appears nowhere in the spec file, and has to work out where it came from. Time travel still works — the entry is pinnable and the before/after snapshots are there — but the question the log stops answering is *which of my steps was this?* On a five-line spec built from three custom commands, that is most of the diagnostic value. ## What to do about it There is no setting that fixes this; it is a design decision each time. 1. **Keep commands shallow.** A command that runs four commands is readable in the log even unlabelled. A command that calls two other custom commands, which each run six, is not. 2. **Log deliberately, or not at all.** If you silence the inner chain, replace it with one entry that carries the arguments that matter — the report id, the role. A silenced chain with nothing in its place is the worst of both. 3. **Use distinctive selectors.** When the log shows only inner commands, a selector like `[data-cy=approve-report]` tells the reader which step they are looking at; `button.primary` does not. Some further habits that keep the log readable: - Put the value that identifies the run in the argument, so the logged `request` row shows `/api/expense-reports/exp-4417` rather than an opaque URL built inside the command. - Resist commands whose only content is a `cy.get()` and an action — those add a name and remove nothing from the log. - When a command must be deep, treat its own failure messages as part of its contract, because the Command Log will not supply the context for you. ## Why this is worth knowing before you abstract The usual argument for a custom command is that it makes a spec read better. That is true of the spec file and false of the failure report, and the failure report is what you read at 9am when CI is red. Weigh both: a command that turns forty lines of sign-in into one is clearly worth an unlabelled chain in the log, because nobody wanted to read that chain anyway. A command that turns two readable lines into one is not, because you have given up the mapping from log row to spec line and bought nothing measurable in return.