Assign an alias for later use. Reference the alias later within a cy.get()
or cy.wait()
command with an @
prefix.
Note:
.as()
assumes you are already familiar with core concepts such as aliases
Syntax
.as(aliasName)
Usage
Correct Usage
cy.get('.main-nav').find('li').first().as('firstNav') // Alias first 'li' as @firstNav cy.route('PUT', 'users', 'fx:user').as('putUser') // Alias that route as @putUser cy.stub(api, 'onUnauth').as('unauth') // Alias that stub as @unauth cy.spy(win, 'fetch').as('winFetch') // Alias that spy as @winFetch
Incorrect Usage
cy.as('foo') // Errors, cannot be chained off 'cy'
Arguments
aliasName (String)
The name of the alias to be referenced later within a cy.get()
or cy.wait()
command using an @
prefix.
Yields
.as()
yields the same subject it was given from the previous command.
Examples
DOM element
Aliasing a DOM element and then using cy.get()
to access the aliased element.
it('disables on click', () => { cy.get('button[type=submit]').as('submitBtn') cy.get('@submitBtn').click().should('be.disabled') })
Route
Aliasing a route and then using cy.wait()
to wait for the aliased route.
cy.route('PUT', 'users', 'fx:user').as('userPut') cy.get('form').submit() cy.wait('@userPut') .its('url').should('contain', 'users')
Fixture
Aliasing cy.fixture()
data and then using this
to access it via the alias.
beforeEach(() => { cy.fixture('users-admins.json').as('admins') }) it('the users fixture is bound to this.admins', function () { cy.log(`There are ${this.admins.length} administrators.`) })
Note the use of the standard function syntax. Using arrow functions to access aliases via
this
won’t work because of the lexical binding ofthis
.
Notes
Reserved words
Alias names cannot match some reserved words.
Some strings are not allowed as alias names since they are reserved words in Cypress. These words include: test
, runnable
, timeout
, slow
, skip
, and inspect
.
as
is asynchronous
Remember that Cypress commands are async, including .as()
.
Because of this you cannot synchronously access anything you have aliased. You must use other asynchronous commands such as .then()
to access what you’ve aliased.
Here are some further examples of using .as()
that illustrate the asynchronous behavior.
describe('A fixture', () => { describe('alias can be accessed', () => { it('via get().', () => { cy.fixture('admin-users.json').as('admins') cy.get('@admins') .then((users) => { cy.log(`There are ${users.length} admins.`) }) }) it('via then().', function () { cy.fixture('admin-users.json').as('admins') cy.visit('/') .then(() => { cy.log(`There are ${this.admins.length} admins.`) }) }) }) describe('aliased in beforeEach()', () => { beforeEach(() => { cy.fixture('admin-users.json').as('admins') }) it('is bound to this.', function () { cy.log(`There are ${this.admins.length} admins.`) }) }) })
Rules
Requirements
.as()
requires being chained off a previous command.
Assertions
.as()
is a utility command..as()
will not run assertions. Assertions will pass through as if this command did not exist.
Timeouts
.as()
cannot time out.
Command Log
Alias several routes
cy.route(/company/, 'fixture:company').as('companyGet') cy.route(/roles/, 'fixture:roles').as('rolesGet') cy.route(/teams/, 'fixture:teams').as('teamsGet') cy.route(/users\/\d+/, 'fixture:user').as('userGet') cy.route('PUT', /^\/users\/\d+/, 'fixture:user').as('userPut')
Aliases of routes display in the routes instrument panel: