vtex / test-tools

Add tests to your VTEX IO app in an instant 🚀

VTEX Test Tools

Add tests to your VTEX IO app in an instant 🚀

Table of Contents

• Install
• Usage
• API
  • React Component
  • React Hooks
  • Messages I18n
  • GraphQL
  • End-to-end flows

Install

yarn add -D @vtex/test-tools @apollo/react-testing@3 react-intl@3

Usage

Add a new script to your react/package.json:

{
  "name": "my-io-app",
  "scripts": {
    "test": "vtex-test-tools test"
  }
}

Add these lines to your .vtexignore:

react/**/__tests__/**
react/**/__mocks__/**
react/**/__snapshots__/**
react/**/*.test.js
react/**/*.test.ts
react/**/*.test.tsx

Run in your terminal:

yarn test

If you're using TypeScript there are a few more steps.

Done! 🎉

Under the hood, we use Jest, so you can pass Jest flags as parameters: read the docs.

API

react module

The module react makes it easy to test VTEX IO React apps.

Example

import React from 'react'
import { render } from '@vtex/test-tools/react'
import HelloWorld from './HelloWorld'

test('should render the Hello!', () => {
  const { getByText } = render(<HelloWorld />)

  const element = getByText(/Hello!/)

  expect(element).toBeDefined()
})

This module uses @testing-library/react (RTL) under the hood, so most of its API is the same (read their docs here).

We added a few more features to the regular render function from RTL, such as a graphql and locale option. You can see more about them down below.

React Hooks

You can also test your custom hooks.

Example

import { hooks } from '@vtex/test-tools/react'
import useCustomHook from './useCustomHook'

const { renderHook, act } = hooks

it('counter should be one', async () => {
  const { result } = renderHook(() => useCustomHook())

  // This waits for the useEffect hook to be triggered and mutate hook state
  await act(() => Promise.resolve())

  expect(result.current).toBe(1)
})

The module uses @react-testing-library/react-hooks under the hood, to understand the reactHook function you can read its doc

Messages

We will automatically wrap your component with an IntlProvider with your app's messages/en-US.json messages.

You can change the default locale being used adding a config to your package.json. Example:

{
  "name": "my-awesome-io-app",
  "vtexTestTools": {
    "defaultLocale": "pt-BR"
  }
}

If you want to change the locale just in a test, you may pass the locale option. Example:

import React from 'react'
import { render } from '@vtex/test-tools/react'
import HelloWorld from './HelloWorld'

test('should render the example translated to portuguese', () => {
  const { getByText } = render(<HelloWorld />, { locale: 'pt' })

  const element = getByText(/Olá!/)

  expect(element).toBeDefined()
})

GraphQL

We automatically wrap your component with an Apollo's MockedProvider.

You can pass your mocked queries to it using the graphql option. Example:

import React from 'react'
import { render, flushPromises } from '@vtex/test-tools/react'
import GraphqlComponent from './GraphqlComponent'
import GET_BOOKS from './getBooks.graphql'

test('should render mock graphql responses', async () => {
  jest.useFakeTimers()

  const bookMock = {
    request: {
      query: GET_BOOKS,
    },
    result: {
      data: {
        books: [
          {
            id: 10,
            title: 'Hello',
          },
        ],
      },
    },
  }

  const { getByText } = render(<GraphqlComponent />, {
    graphql: { mocks: [bookMock] },
  })

  expect(getByText(/Loading/)).toBeDefined()

  await flushPromises()
  jest.runAllTimers()

  expect(getByText(/Hello/)).toBeDefined()
})

End-to-end flows

We offer hooks to make writing end-to-end tests easier.

Extended commands:

• clickById
• getById
• typeById

Custom methods:

• goToSearchPage
• goToProductPageByShelf
• checkText
• checkIfElementExists
• openCart
• closeCart
• clearCart
• fillAndCheckShippingSimulator
• scrollToId

Example:

import { openCart } from "@vtex/test-tools/cypress"

describe('Searchbar', () => {
  before(() => {
    cy.intercept(/operationName=ProductsSuggestionsQuery/, {
      fixture: 'product-suggestions-query.json',
    }).as('searchSuggestionsLoad')
  })

  it('finds a very specific product using the search bar', () => {
    cy.visit('/')

    cy.getById('searchBarInput').eq(0).type('Product')

    cy.getById('searchSuggestionsItem').contains('Product').click()

    cy.clickById('addToCart')

    openCart()

    ...
  })
})

You can check more details of these hooks in the links below:

• cypress/support/commands
• cypress/utils

Examples

These are some common use cases that might be helpful to see how it's done:

• Debugging tests in VS Code

• Testing a React Hook

• Testing a React component

• Testing a React component using Typescript

• Testing a component using CSS Modules

• Testing a component using GraphQL

• Testing a component using React Hooks

• Testing a component translating in another locale

• Testing end-to-end flows using Cypress

License

MIT © VTEX

test-tools's Issues

How can i ignore module vtexjs?

Since vtexjs is a native module in javascript, i'm trying to test the checkout with checkout-ui-cusotm but it tells me that vtexjs is undefined and orderFormId is undefined, so how can I test with all the vtexjs package included

TypeScript tests are not working

It throws an error of missing @types/jest.

I tried to solve this issue:

• Placing tsconfig.json in the user react folder
• Placing tsconfig.json in the test-tools folder
• Using tsConfig option of ts-jest https://kulshekhar.github.io/ts-jest/user/config/tsConfig

None worked.

I'm considering replacing ts-jest with the babelTransform, just like create-react-app does.

Locale is not working to test different different languages

These two approaches:

"vtexTestTools": {
    "defaultLocale": "pt"
  },

or

test('should render the example translated to portuguese', () => {
  const { getByText } = render(
    <HelloWorld />,
    { locale: 'pt' }
  )

  const element = getByText(/Olá!/)

  expect(element).toBeDefined()
})

are not working as expected and they are falling into the default language (english)

Make Jest export global

Find a way to export Jest type definitions in a global way, kinda like create-react-app does it, so that the user does not need to import @vtex/test-tools/react in order to use Jest functions without TypeScript complaining.

Test not find module vtex.css-handles

when i has an import from 'vtex.css-handles' in my code, test print this error:

How to do a test-tool resolve 'vtex.css-handles' or mock this module?

Node 12 not supported by jest

Hi,
unfortunately jest update to version 29 kicked support for node 12.
Trying to link (or publish/deploy) a vtex-app with vtex/test-tools dependency now fails with

Only workaround so far is to remove vtex/test-tools and jest completly from package.json, deleting node_modules and reinstall (removing jest from tsconfig also)

So vtex apps can't be tested anymore!

How can I add a configuration when running the coverage?

We need to run the tests with the following configuration

coverageThreshold: { "global": { "branches": 80, "functions": 80, "lines": 80 }

Use `en.json` as default translation and fallback to `en-US.json` and another fallback

Today the default of @vtex/test-tools is to use en-US.json as the default translation. We should instead use en.json as the default.

It should be:

Default	Fallback	Fallback
en.json	en-US.json	Empty object ({})

Add definitions of locale and graphql to render function second parameter