Search
⌘K
    to navigateEnterto select Escto close

    data-cy conventions

    Targeting the element by tag, class or id is very volatile and highly subject to change. You may swap out the element, you may refactor CSS and update ID's, or you may add or remove classes that affect the style of the element.

    Instead, adding the data-cy attribute to the element gives us a targeted selector that's only used for testing.

    The data-cy attribute will not change any CSS style or a JS behavior, meaning it's not coupled to the behavior or styling of an element.

    Additionally, it makes it clear to everyone that this element is used directly by the test code.

    Conventions for adding data-cy

    There are no particular conventions for adding data-cy, but here in BigBinary we have set our own conventions for better code readability.

    1. data-cy must be added in the following format:
    1data-cy="functionality-name-field-name-type-of-the-field"
    1. When we use cy as attribute we use hyphen i.e. data-cy.

    But, in a react application we need to it pass as a prop to another component. In some cases, data-cy might not work, in that case we can use dataCy:

    1  <Button
    2    style="icon"
    3    data-cy=""
    4    ...
    5  />
    6
    7  NavItem({
    8    icon,
    9    link,
    10    dataCy,
    11    ...
    1. Everything should be in lowercase while adding data-cy.

    e.g. Consider we want to add data-cy to the application's icon, say AceInvoiceIcon:

    1// Incorrect
    2data-cy="aceInvoice-Icon"
    3
    4// Correct
    5data-cy="ace-invoice-icon"
    6
    
    1. Adding data-cy for different elements:
    • data-cy for labels

    e.g. Adding data-cy to a label, say "Email" label:

    1data-cy="email-label"
    • data-cy for links

    e.g. Adding data-cy to any link, say signup link:

    1// Incorrect
    2data-cy="signup"
    3
    4// Correct
    5data-cy="signup-link"
    • data-cy for text fields

    e.g. Adding data-cy for email text field on login page:

    1// Incorrect
    2data-cy="login-email"
    3
    4// Correct
    5data-cy="login-email-text-field"
    • data-cy for checkboxes

    e.g. Adding data-cy for 'remember me' checkbox on login page:

    1// Incorrect
    2data-cy="login-remember-me"
    3
    4// Correct
    5data-cy="login-remember-me-check-box"
    • data-cy for radio buttons

    e.g Adding data-cy for the radio button for the role of a member:

    1// Incorrect
    2data-cy="member-role-button"
    3
    4// Correct
    5data-cy="member-role-radio-button"
    • data-cy for dropdown lists

    e.g. Adding data-cy for dropdown lists of countries:

    1// Incorrect
    2data-cy="country-list"
    3
    4// Correct
    5data-cy="country-drop-down-list"
    • data-cy for buttons

    e.g. Adding data-cy for submit details button on login page:

    1// Incorrect
    2data-cy="login-submit"
    3
    4// Correct
    5data-cy="login-submit-button"

    e.g. Adding data-cy for delete button to delete a team member:

    1// Incorrect
    2data-cy="team-member-delete"
    3
    4// Correct
    5data-cy="team-member-delete-button"
    1. Sometimes the element is very common throughout the whole application, in such cases data-cy values for these elements can be kept in selectors/common.

    e.g. In neeto products, the heading selector is very common part for different pages in the application. Hence, the data-cy value for this element can be generic.

    1data-cy="heading"
    1. neeto applications:

    In neeto apps, we are using neetoUI component library. In neetoUI, data-cy can be added or already added to most of the elements. However, it uses some external libraries as well. In such cases, we can't add data-cy to those elements and we can use the selectors available for that element. e.g. The dropdowns in the neeto are custom dropdowns and data-cy cannot be added to such elements.

    Note: We should try to maintain data-cy whenever possible.

    dataCy function

    We can define a function dataCy in Support/utils/common as:

    1export const dataCy = (value, suffix = "") => {
    2  return `[data-cy='${value}']${suffix}`;
    3};
    

    which could return selector while passing the data-cy value of the element. This is done to keep the code organized and clean. So instead of [data-cy=client-submit-button] we can use dataCy("client-submit-button").

    suffix argument is used when we need to select an element from a group of similar elements which have the same data-cy value or in case we need select a child element from a parent element with a particular data-cy.

    Let take an example:

    Here the clients in the list all have data-cy value of client-name-row-link. So if need to click the first client, we can pass "eq(0)" as suffix. So the dataCy function will return [data-cy='client-name-row-link']:eq(0) which will be used get the element.

    Now the selectors can be defined as:

    1import { dataCy } from "Support/utils/common";
    2
    3export const clientsSelectors = {
    4  continueSubmitButton: dataCy("client-submit-button"),
    5  nameTextField: dataCy("client-name-text-field")
    6}
    Previous
    Next