blur
Remove focus from an element and fire its blur and focusout events. Use it
to test what your app does when a field loses focus.
It is unsafe to
chain further commands that rely on the subject after .blur().
Syntax​
.blur()
.blur(options)
Usage​
Correct Usage
cy.get('[type="email"]').blur() // Blur the focused email input
cy.get('[tabindex="1"]').blur() // Blur the focused element with tabindex
cy.window().blur() // Blur the window
Incorrect Usage
cy.blur('input') // Errors, cannot be chained off 'cy'
cy.get('li').blur() // Errors, subject contains more than one element
Arguments​
options (Object)
Pass in an options object to change the default behavior of .blur().
| Option | Default | Description |
|---|---|---|
log | true | Displays the command in the Command Log |
force | false | Forces the action, disables checking if element is focused |
timeout | defaultCommandTimeout | Time to wait for assertions chained to .blur() to pass before timing out |
Yields ​
.blur()yields the same subject it was given.- It is unsafe
to chain further commands that rely on the subject after
.blur().
Examples​
No Args​
Blur the comment input​
cy.get('[name="comment"]').type('Nice Product!')
cy.get('[name="comment"]').blur()
Options​
Blur the first input​
Setting force to true in the options disables checking whether the input
currently has focus.
cy.get('input').first().blur({ force: true })
Workflows​
Show a validation message when a field loses focus​
cy.get('#email').type('not-an-email')
cy.get('#email').blur()
cy.get('#email-error').should('be.visible')
Format a value when a field loses focus​
cy.get('#price').type('19.5')
cy.get('#price').blur()
cy.get('#price').should('have.value', '19.50')
Autosave a field when it loses focus​
Blurring a field you typed into fires its change event, so an app that saves
on change sends its request when .blur() runs. Stub the request with
cy.intercept() and wait on it with
cy.wait().
cy.intercept('POST', '/api/notes', { statusCode: 204 }).as('saveNotes')
cy.get('#notes').type('Ships Friday')
cy.get('#notes').blur()
cy.wait('@saveNotes').its('request.body').should('include', 'Ships Friday')
Confirm the element no longer has focus​
cy.get('#email').focus()
cy.get('#email').blur()
cy.get('#email').should('not.have.focus')
Test what your app does when the window loses focus​
Blurring the window fires a blur event on it, the same event the browser sends
when the user switches to another tab or app.
cy.window().blur()
cy.get('#status').should('have.text', 'paused')
Notes​
Actionability​
Blur is not an action command​
.blur() doesn't wait for
actionability the way action
commands such as .click() do. A user never blurs
an element on its own; they click or tab somewhere else. .blur() removes focus
without that other action, so a blur test doesn't depend on it.
Subjects​
Blurring the window leaves the focused element alone​
.blur() accepts the window as its subject, so cy.window().blur() fires a
blur event on the window. Focus itself does not move: whichever element held
it still does, and document.activeElement is unchanged.
Blurring the body doesn't fire a blur event​
.blur() also accepts the body without it having focus, but the browser never
fires blur on the body, so Cypress doesn't simulate one. Focus stays where it
was.
Events​
Blurring a field you typed into fires its change event​
When the element has a value change waiting from .type()
or .clear(), .blur() fires the change event first,
then blur, the same order the browser uses when a user leaves the field.
Rules​
Requirements ​
.blur()requires being chained off a command that yields a DOM element or the window..blur()requires the subject to contain a single element..blur()requires the element to currently have focus, unless you pass{ force: true }. The window and thebodyare exempt, since neither reports as the focused element.
Assertions ​
.blur()automatically waits for assertions you've chained to pass.
Timeouts ​
.blur()can time out waiting for assertions you've added to pass.
Command Log​
Blur a textarea after typing.
cy.get('[name="comment"]').focus()
cy.get('[name="comment"]').type('Nice Product!')
cy.get('[name="comment"]').blur()
The commands above display in the Command Log as:
Clicking the blur command in the Command Log prints the following to the
console:
History​
| Version | Changes |
|---|---|
| 3.0.3 | Added support for blurring the body; blurring the window no longer moves focus |
| 0.20.0 | Added support for blurring the window |
| 0.11.10 | Added option force |
| 0.8.0 | .blur() fires change events for fields whose value changed |