# Utilities

Examples of the use of methods from other commonly used libraries in Cypress, for a full reference of commands, go to docs.cypress.io

# Cypress._

To call a lodash method, use the Cypress._.method() command.

cy.request('https://jsonplaceholder.cypress.io/users').then(
  (response) => {
    let ids = Cypress._.chain(response.body).map('id').take(3).value()

    expect(ids).to.deep.eq([1, 2, 3])
  },
)

# Cypress.$

To call a jQuery method, use the Cypress.$ command.

<ul class="list-group utility-jquery">
  <li class="list-group-item">
    <span class="badge">5</span>
    Watches
  </li>
  <li class="list-group-item">
    <span class="badge">14</span>
    Sweaters
  </li>
  <li class="list-group-item">
    <span class="badge">22</span>
    Scarves
  </li>
</ul>
<script>
  document
    .querySelector('li.list-group-item')
    .addEventListener('click', function (e) {
      e.target.classList.add('active')
    })
</script>
  • 5 Watches
  • 14 Sweaters
  • 22 Scarves
let $li = Cypress.$('.utility-jquery li:first')

cy.wrap($li)
  .should('not.have.class', 'active')
  .click()
  .should('have.class', 'active')

# Cypress.Blob

To work with blobs, convert strings, and other utility functions, use the Cypress.Blob library.

<div class="utility-blob"></div>
cy.get('.utility-blob').then(($div) =>
  // https://github.com/nolanlawson/blob-util#imgSrcToDataURL
  // get the dataUrl string for the javascript-logo
  Cypress.Blob.imgSrcToDataURL(
    'https://example.cypress.io/assets/img/javascript-logo.png',
    undefined,
    'anonymous',
  ).then((dataUrl) => {
    // create an '<img />' element and set its src to the dataUrl
    let img = Cypress.$('<img />', { src: dataUrl })
    // need to explicitly return cy here since we are initially returning
    // the Cypress.Blob.imgSrcToDataURL promise to our test
    // append the image
    $div.append(img)

    cy.get('.utility-blob img')
      .click()
      .should('have.attr', 'src', dataUrl)
  }),
)

# Cypress.minimatch

To test out glob patterns against strings, use the Cypress.minimatch library.

let matching = Cypress.minimatch(
  '/users/1/comments',
  '/users/*/comments',
  {
    matchBase: true,
  },
)

expect(matching, 'matching wildcard').to.be.true

matching = Cypress.minimatch(
  '/users/1/comments/2',
  '/users/*/comments',
  {
    matchBase: true,
  },
)
expect(matching, 'comments').to.be.false

// ** matches against all downstream path segments
matching = Cypress.minimatch(
  '/foo/bar/baz/123/quux?a=b&c=2',
  '/foo/**',
  {
    matchBase: true,
  },
)
expect(matching, 'comments').to.be.true

// whereas * matches only the next path segment

matching = Cypress.minimatch(
  '/foo/bar/baz/123/quux?a=b&c=2',
  '/foo/*',
  {
    matchBase: false,
  },
)
expect(matching, 'comments').to.be.false

# Cypress.Promise

To instantiate a new Bluebird promise, use Cypress.Promise.

let waited = false

/**
 * @return Bluebird<string>
 */
function waitOneSecond() {
  // return a promise that resolves after 1 second
  // @ts-ignore TS2351 (new Cypress.Promise)
  // eslint-disable-next-line no-unused-vars
  return new Cypress.Promise((resolve, reject) => {
    setTimeout(() => {
      // set waited to true
      waited = true

      // resolve with 'foo' string
      resolve('foo')
    }, 1000)
  })
}

cy.then(() =>
  // return a promise to cy.then() that
  // is awaited until it resolves
  // @ts-ignore TS7006
  waitOneSecond().then((str) => {
    expect(str).to.eq('foo')
    expect(waited).to.be.true
  }),
)

// you can also wait on a promise from the application code
// using https://on.cypress.io/wrap
cy.wrap(waitOneSecond()).should('equal', 'foo')