In Cypress, what does Cypress.log() give a custom command that cy.log() does not?

## Two different jobs Both write to the Command Log, but they are not variants of one another. `cy.log()` is a **command**: you call it from a test, it takes its place in the queue, and it appends one entry that says what you told it to say. Its message accepts Markdown, it takes any number of extra arguments (`cy.log('assigned', ticketId, agent)`) which are printed to the console when the entry is clicked, it yields `null`, and no assertion can be chained onto it. It is narration — a signpost in a long spec. `Cypress.log()` is the **internal API for controlling what gets printed to the Command Log**, and it is what the built-in commands themselves call. You reach for it when a custom command would otherwise be a black box: the log shows its name and nothing about what it did, so a failure inside it reads as one opaque line. ## The options that matter | Option | Default | What it does | |---|---|---| | `name` | the command's name | the name shown in the Command Log | | `displayName` | the command's name | overrides `name` for display only — useful for a short label | | `message` | the command args | the text beside the name in the entry | | `consoleProps` | `function() {}` | a function returning an object, printed to the DevTools console when the entry is clicked | | `$el` | `undefined` | the jQuery element the command acted on; highlights it in the app preview | | `type` | `'parent'` | `'parent'` or `'child'` — child entries render indented | | `autoEnd` | `true` | set `false` to close the entry yourself, which async commands need | | `end` | `false` | set `true` to mark the entry finished the moment it is created | The one people underuse is `consoleProps`. It is a **function**, not an object, and Cypress calls it when you click the entry — so it can close over values that only exist inside your command and present them under readable keys. That is where the ticket id, the response status and the response body belong: one click away in DevTools, instead of gone. ## The Log object and asynchronous helpers `Cypress.log()` returns a `Log` you can keep hold of: - `log.end()` — mark it passed and finished. - `log.error(err)` — turn the entry red. **This only changes how the entry looks; it does not fail the test.** You must still rethrow the error, or the run carries on green with a red line in the log. - `log.set(key, value)` or `log.set(options)` — update attributes later, which is how you attach `consoleProps` containing data that did not exist when the entry was created. - `log.get()` / `log.get(attr)` — read the entry's current attributes. - `log.snapshot()` / `log.snapshot(name)` — capture the DOM against this entry; named snapshots become labelled tabs when the entry is pinned. For anything that finishes asynchronously, the pattern is: 1. Create the entry with `autoEnd: false` so it stays open. 2. Do the work. 3. `log.set({ consoleProps: () => ({ ...now-known data }) })`. 4. `log.end()` on success, or `log.error(err)` **and rethrow** on failure. Forget step 4 and the entry sits pending forever, which reads to the next person as a hung command. ## The other half of the same decision: `{ log: false }` Shaping a command's log entry usually comes in pairs. `Cypress.log()` adds the entry you want; `{ log: false }` — accepted by most built-in commands — suppresses the entries you do not. A helper that fires a `cy.request()` and a couple of `cy.window()` calls to set up a ticket produces three lines that say nothing useful; silencing them and adding one `Cypress.log()` for the helper as a whole turns that into one legible step. What `{ log: false }` does **not** do is change behaviour. The command still runs, and if it fails the test still fails — you have simply removed the line that would have said where. ## A worked shape ```js Cypress.Commands.add('assignTicket', (ticketId, agent) => { const log = Cypress.log({ name: 'assignTicket', displayName: 'assign', message: `#${ticketId} to ${agent}`, autoEnd: false, }) cy.request({ method: 'POST', url: `/api/tickets/${ticketId}/assign`, body: { agent }, log: false, }).then((res) => { log.set({ consoleProps: () => ({ ticketId, agent, status: res.status, body: res.body }) }) log.end() }) }) ``` In the Command Log that is one `assign` entry reading `#4821 to dana`; clicking it prints the ticket id, the agent, the HTTP status and the response body. Compare it with the same helper writing `cy.log('assigning ticket')` — a line that tells you the helper started and nothing about why it did not finish.