Using Cypress to test in Salesforce

Solutions for challenges faced with the framework setup

Published in

Smartbox engineering

7 min readAug 11, 2020

Salesforce is a Customer Relationship Management (CRM) platform that includes modules for sales, service, marketing, analytics, and more. The tool enables developers to write and execute unit tests through the Apex testing framework. However, if you are either a tester or a developer working with Salesforce, you have probably faced the need for testing a feature in the UI.

In this article, I’m going to share some tips to help you create your Salesforce UI testing framework using Cypress, based on the challenges I faced when creating my own. The main advantage of using Cypress, in my opinion, is the ease of set up. Who works with Selenium, for example, knows how time-consuming it can be to define and configure the dependencies before start writing the tests.

The goal of this article is not teaching how to use Cypress from the basics. If you’re not familiar with it yet, I recommend the series created by Soraia Fernandes. She provides a solid walk-through on how to create your first project using Page Objects and Cucumber, which is the same approach I like to use.

The examples were tested using the following versions of the dependencies:

"devDependencies": {
    "cypress": "4.11.0",
    "cypress-xpath": "1.6.0",
    "jsforce": "1.9.3"
}

Testing in multiple Sandboxes

In Salesforce, it’s possible to create copies of the production organization for different purposes, such as development and testing. These copies are called Sandboxes and are isolated from the production org. It means changes made in a Sandbox won’t impact the data or the code in production.

Depending on your team’s process, you may need to run your tests in different Sandboxes. Luckily, Cypress provides simple ways of doing it. The one I like the most is having multiple configuration files containing environment variables for each Sandbox.

// cypress/config/cypress.test.json{
   "baseUrl": "https://mysandbox.test.salesforce.com","env": {
      "salesforce": {
          "loginUrl"      : "https://test.salesforce.com",
          "username"      : "<my_username>",
          "password"      : "<my_password>",
          "accessToken"   : "<my_accessToken>"
      }
   }
}// cypress/config/cypress.dev.json{
   "baseUrl": "https://mysandbox.dev.salesforce.com","env": {
      "salesforce": {
          "loginUrl"      : "https://test.salesforce.com",
          "username"      : "<my_username>",
          "password"      : "<my_password>",
          "accessToken"   : "<my_accessToken>"
      }
   }
}// cypress/config/cypress.prod.json{
   "baseUrl": "https://mysandbox.prod.salesforce.com","env": {
      "salesforce": {
          "loginUrl"      : "https://login.salesforce.com",
          "username"      : "<my_username>",
          "password"      : "<my_password>",
          "accessToken"   : "<my_accessToken>"
      }
   }
}

To execute the scenarios considering specific configuration files, create scripts for them in the package.json file using the --config-file tag.

// cypress/package.json"scripts": {"cy:open:dev": "cypress open --config-file ./cypress/config/cypress.dev.json","cy:open:test": "cypress open --config-file ./cypress/config/cypress.test.json","cy:run:dev": "cypress run --config-file ./cypress/config/cypress.dev.json","cy:run:test": "cypress run --config-file ./cypress/config/cypress.test.json"}

Open Cypress and go to Settings > Configuration to check the environment variables.

yarn run cy:open:test

The Environment Variables are displayed in the Configuration section

The environment variables are now available for use in the tests and accessible by using Cypress.env(). There will be a practical use for it in the next topic.

Login into Salesforce

After reading some forums on the topic, I noticed cases in which people gave up using Cypress to test in Salesforce because they faced difficulties to log in. The main mistake, in this case, is probably trying to use the UI for that. When taking such an approach, the following error is displayed:

Whoops, there is no test to run. — Error in the App Preview

A good practice I like to follow is to don’t use the UI to set up state. Login is a crucial part of the test because it needs to run in every single scenario. So, it makes sense these steps execute as fast as possible. Having this in mind, we can create a login() method using cy.request() to log in and, then, using cy.visit() to open your instance page.

// cypress/support/commands.jsCypress.Commands.add('login', () => {
   const loginUrl = Cypress.env("salesforce").loginUrl
   const username = Cypress.env("salesforce").username
   const password = Cypress.env("salesforce").passwordcy.request(`${loginUrl}/?un=${username}&pw=${password}`)
     .then(() => {
        cy.visit('/')
     })
})

Now, cy.login() is available for use. If the project uses Cucumber, add a Before step to a feature file.

// cypress/support/step-definitions/common-steps.jsBefore(() => {
   cy.login()
})

It’s also possible to use root-level hooks in Mocha. Before every test in the spec files, Cypress will check cypress/support/index.js file, which makes a good idea to place a beforeEach command there.

// cypress/support/index.jsbeforeEach(() => {
   cy.login()
})

Salesforce homepage opened in Cypress during test execution. — User logged in Salesforce in the test execution

It’s important to have in mind that the IP of the machine or server running Cypress must be whitelisted in Salesforce. Read more on Login IP Whitelist.

Taking advantage of jsForce

Test data is an important element for the success of automation projects. When writing scenarios to test in Salesforce, we need to have Accounts, Products, Opportunities, and the idea of generating this data using the UI might cross our minds. However, as mentioned before, we should not use it to set up a state.

To help with this issue, we can take advantage of jsForce, a JavaScript Library that utilizes Salesforce’s API. jsForce allows the connection with Salesforce and provides methods to CRUD, query, and much more. To add it to the project, just run:

yarn add jsforce@1.9.3 --dev

The strategy to use jsForce with Cypress will be creating tasks like salesforceCreate(), salesforceUpdate(), salesforceQuery() in cypress/plugins/index.js and using them to add new commands to the project.

For any of those tasks, firstly it’s necessary to connect and log into Salesforce. jsForce provides several ways of doing that. The chosen here was the Username and Password Login, as the credentials are available in the environment variables.

The following example makes use of the jsForce method create. It allows the creation of one or more records of the type given in the first argument: objectType. It’s valid to highlight that all the environment variables are accessible from cypress/plugins/index.js. However, Cypress.env() won’t work, making us use config.env instead.

// cypress/plugins/index.jsconst jsforce = require('jsforce');/**
*
* @param {string} objectType Type of the object to be created, e.g., 'Account', 'Opportunity', 'Product2'
* @param {*} object Salesforce object specificification, e.g., { Name: 'Test Account', Phone: '0123456789' }
* @param {*} config
*/
function createObject(objectType, object, config) {const username = config.env.salesforce.username
   const password = config.env.salesforce.password
                  + config.env.salesforce.accessToken
   const loginUrl = config.env.salesforce.loginUrlreturn new Promise((resolve, reject) => {
      var conn = new jsforce.Connection({loginUrl: loginUrl})conn.login(username, password, err => {
         if (err) reject(err)conn.sobject(objectType).create(object, (err, ret) => {
            if (err || !ret.success) { return console.error(err, ret) }console.log(`Created ${objectType} with id : ${ret.id}`)
            return resolve(ret)})
      })
   })
}module.exports = (on, config) => {
   on('task', {
      salesforceCreate ({objectType, object}) {
         return createObject(objectType, object, config)
      },
      // Add new tasks created here
   }
}

The next step is to add a new command, e.g., createAccount().

// cypress/support/commands.jsCypress.Commands.add('createAccount', (obj) => {
   cy.task('salesforceCreate', ({objectType: 'Account', object: obj}))
})

All setup! Now the new command can be used in the test file.

// your/test/file.jscy.createAccount({ Name: 'My Account #1' })
  .then((newAccount) => {
     cy.wrap(newAccount.id).as('newAccountId')
})

The jsForce documentation is quite complete. Refer to it whenever you need new methods in your project.

A suggestion for creating objects…

When creating new objects, we generally need them to have specific values to attend our needs in a given scenario. For such, a nice strategy is to create classes to represent Salesforce objects, such as Account or Opportunity, and define the Field API Names as instance variables.

// cypress/domain/account.jsexport class Account {AccountNumber
   City__c
   Country__c
   Id
   Phone
   RecordTypeIdsetAccountNumber = (accountNumber) => {
      this.AccountNumber = accountNumber
   }setCity = (city) => {
      this.City__c = city
   }setCountry = (country) => {
      this.Country__c = country
   }setId = (id) => {
      this.Id = id
   }setPhone = (phone) => {
      this.Phone = phone
   }setRecordTypeId = (recordTypeId) => {
      this.RecordTypeId = recordTypeId
   }
}

In the test file, we can instantiate an object and set values to it as needed. Then, use it to, for example, create a Salesforce Object.

// your/test/file.jsimport { Account } from "path/to/class/account"const account = new Account()account.setAccontNumber("123456")
account.setCity("Tokyo")
account.setCountry("Japan")cy.salesforceCreateAccount(account)
  .then((newAccount) => {
     cy.wrap(newAccount.id).as('newAccountId')
})

Selecting elements with XPath

If you have already tried writing automation tests in Salesforce, you probably know that using DOM id’s when selecting elements is not the best approach as they constantly change. To avoid this problem, a solution that has proven to be very satisfactory in my tests is to write selectors using the relative XPath with the field label in it.

const nameField = `//*[text()='Name']/parent::span/following-sibling::div[1]//a`

This approach has some advantages:

Risk reduction of an element not being found during the test execution;
Improvement on the selector’s readability;
Better maintainability.

To use XPath in Cypress, add a Custom Command plugin called cypress-xpath to the project.

yarn add cypress-xpath --dev

Include it to cypress/support/index.js

// cypress/support/index.jsrequire('cypress-xpath')

The class below uses XPath to select the Account page elements.

// your/page/object/file.jsconst accountNumberField = `//*[text()='Category']/parent::span/following-sibling::div[1]//a`
const cityField          = `//*[text()='City']/parent::label/following-sibling::input`
const countryField       = `//*[text()='Country']/parent::label/following-sibling::input`
const phoneField         = `//*[text()='Phone']/parent::label/following-sibling::input`export class AccountPage {typeAccountNumber(accNumber) {
     cy.xpath(accountNumberField)
       .clear()
       .type(accNumber)
   }typeCity(city) {
      cy.xpath(cityField)
        .clear()
        .type(city)
   }typeCountry(country) {
      cy.xpath(countryField)
        .clear()
        .type(country)
   }typePhone(phone) {
      cy.xpath(phoneField)
        .clear()
        .type(phone)
   }
}

Conclusion

I hope this article helped you to bypass some initial difficulties to start your Salesforce UI automation framework in Cypress. If you have different strategies, suggestions, or difficulties not listed here, feel free leave comment. We may be able to help each other.