Teste unit�rio com Jest

Jest � um framework de teste unit�rio de c�digo aberto em JavaScript criado pelo Facebook a partir do framework Jasmine. Jest � uma das ferramentas de teste unit�rio mais difundidas dentro da comunidade de JavaScript.

Vis�o Geral

O Jest foi inicialmente criado para testar o framework React, tamb�m criado pelo Facebook. Por�m sua implementaç�o se tornou muito mais ampla, sendo utilizado como ferramenta de teste unit�rio para diversas plataformas JavaScript como Node e Redux, e at� mesmo plataformas em TypeScript como Angular e Ionic.

Por exemplo, quando precisamos testar se uma funç�o de consulta est� se comunicando devidamente com uma API, o mais comum � executar essa funç�o e exibir o resultado no console:

let cliente_dao = new ClienteDAO()
    cliente = cliente_dao.find_by_id(10)
    console.log(cliente.nome)
    //o resultado esperado � "Edson Arantes do Nascimento"

Em um projeto maior esse tipo de teste tende a se tornar invi�vel e inseguro a medida que a complexidade do m�dulo e da unidade aumentam. � natural sentir falta de uma metodologia de testes, que permita medir a cobertura de teste do c�digo, tornando f�cil criar os cen�rios nos quais as falhas ser�o percebidas. Os testes unit�rios suprem essas e outras car�ncias do processo de teste de c�digo.

test('Busca o nome do cliente pelo id', () => {
      let cliente_dao = new ClienteDAO()
      cliente = cliente_dao.find_by_id(10)
      expect(cliente.nome).toBe("Edson Arantes do Nascimento")
    })

O programador JavaScript conta com uma ferramenta muito poderosa e flex�vel para implementar testes unit�rios em seus projetos. At� a data dessa documentaç�o o Jest est� na vers�o 23.3. Jest � compat�vel com o EcmaScript 5 em diante

Instalaç�o

O Jest pode ser instalado pelo Yarn ou pelo NPM como uma depend�ncia externa.

yarn

Para adicionar o Jest ao seu projeto basta rodar o comando.

yarn add --dev jest

npm

Para adicionar o Jest ao seu projeto basta rodar o comando:

npm install --save-dev jest

Configuraç�o

Sim, o Jest utiliza o pr�prio gerenciador de pacotes usado em sua instalaç�o para executar os testes atrav�s do comando test, para isso � necess�rio adicionar ao documento package.json a seguinte sess�o:

{
      "scripts": {
        "test": "jest"
      }
    }

Escrevendo Testes

Nesta seç�o veremos como escrever diversos testes com o Jest, a fim de aprender como lidar com essa ferramenta em diferentes cen�rios.

Vis�o geral

Para um primeiro exemplo vamos testar a funç�o freteGratis dentro do m�dulo descontos.js:

function freteGratis (valor) {
  return valor >= 150
}

Para test�-lo vamos criar o arquivo descontos.test.js, dentro desse arquivo iremos chamar a funç�o test que ser� reconhecida pelo Jest como um teste efetivamente, como segundo argumento de test passamos uma funç�o an�nima sem argumentos, e nessa funç�o executamos a funç�o expect, e � essa funç�o que ir� verificar o resultado do c�digo sendo testado:

const freteGratis = require('./descontos').freteGratis()

test('freteGratis � verdadeiro para 200', () => {
  expect(freteGratis(200)).toBeTruthy()
})

Gratis = require('./descontos').freteGratis() test('freteGratis � verdadeiro para 200', () => { expect(freteGratis(200)).toBeTruthy() })

Em seguida rodamos o seguinte comando no terminal para executar o teste:

npm test

Ou ent�o:

yarn test

Na linha de comando o Jest ir� notificar se o teste passou ou se falhou.

"descontos"

 PASS  test/descontos.test.js
  OK freteGratis � verdadeiro para 200 (5ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        3.814s
Ran all test suites matching /descontos/i.

Na pr�tica

Jest utiliza de "matchers" (combinadores) para realizar os testes efetivamente. Existem diversos matchers para cada situaç�o em particular dentro do contexto de testes. Os matchers s�o implementados a partir da chamada de expect() seguinte a sintaxe:


test('descriç�o do teste', () => {
    expect("valor esperado").toMatch("c�digo testado");
});

Exemplo 1

O mais comum em teste unit�rio costuma ser o teste de igualdade. O Jest possui matchers de comparaç�o que independem do tipo, estes s�o:

A funç�o .toBe(valor) testa se o valor passado � id�ntico ao esperado em valor e tipo .

test("resultados devem ser id�nticos",
    () => {
        let geladeira = produto.findGeladeiraById(12)
        expect(geladeira.modelo).toBe('Eletrolux')
})

A funç�o .toEqual(valor) testa recursivamente cada valor do objeto ou array.

test("resultados devem possuir os mesmo atributos",
    () => {
        let geladeira = produto.findGeladeiraById(12)
        expect(geladeira).toEqual({preco: 1249.99, ano: '2017', modelo: 'Eletrolux'})
})

Para cada matcher de comparaç�o � poss�vel usar o .not para fazer uma comparaç�o oposta.

test("resultados n�o devem possuir os mesmo atributos",
    () => {
        let geladeira = produto.findGeladeiraById(12)
        expect(geladeira).not.toEqual({preco: 1249.00, ano: '2014', modelo: 'Brastemp'})
})

Exemplo 2

A funç�o toBeNull Testa se o resultado passado tem valor igual a null.

var id = "56e6dd2eb4494ed008d595bd"

test('resultado precisa ser null', () => {
    expect(UserModel.findById(id, user => user.toObject() )).toBeNull()
})

A funç�o toBeUndefined testa se o resultado passado tem valor igual a undefined.

test('resultado precisa ser undefined', () => {
    expect(UserModel.findById(id, user => user.toObject() )).toBeUndefined()
})

A funç�o toBeDefined testa se o resultado passado n�o tem valor igual a undefined.

test('resultado n�o pode ser undefined', () => {
    expect(UserModel.findById(id, user => user.toObject() )).toBeDefined()
})

A funç�o toBeTruthy testa se o resultado passado tem valor que pode ser passado como true em um if.

test('resultado precisa ser true', () => {
    expect(UserModel.findById(id, user => user.toObject() )).toBeTruthy()
})

A funç�o toBeFalsy testa se o resultado passado tem valor que pode ser passado como false em um if.

test('resultado precisa ser false', () => {
    expect(UserModel.findById(id, user => user.toObject() )).toBeFalsy()
})

Exemplo 3

Matchers usados para fazer comparaç�es num�ricas:

A funç�o toBeGreaterThan testa se o resultado passado � maior que o esperado.

test('Dolar deve ser maior que Real', 
    () => {
        expect(moedas.getDolar()).toBeGreaterThan(moedas.getReal())
})

A funç�o toBeGreaterThanOrEqual testa se o resultado passado � maior ou igual ao esperado.

test('salario deve ser maior ou igual ao sal�rio m�nimo', 
    () => {
        expect(funcionario.getSalario()).toBeGreaterThanOrEqual(api.salarioMinimo())
})

A funç�o toBeLessThan testa se o resultado passado � menor que o esperado.

test('Peso deve ser menor que Libra', 
    () => {
        expect(moedas.getPeso()).toBeLessThan(moedas.getLibra())
})

A funç�o toBeLessThanOrEqual testa se o resultado passado � menor ou igual ao esperado.

test('salario de n�o comissionado deve ser menor ou igual ao sal�rio de comissionado', 
    () => {
        expect(naoComissionado.getSalario()).toBeLessThanOrEqual(comissionado.getSalario())
})

Nota: Os matchers toBe e toEqual s�o usados para testar equidade num�rica.

Exemplo 4

� poss�vel verificar se uma certa string est� dentro de uma express�o maior com o comando toMatch

test("Uma palavra dentro de outra", () => {
    expect('Inconstitucionalissimamente').toMatch(/constitucional/)
})

Exemplo 5

� poss�vel verificar se um array possui um elemento em espec�fico com toContain.

const verbosHttp = [
    'GET',
    'POST',
    'PUT',
    'DELETE'
]
test('O verbo PUT est� na lista' ,()=>{
    expect(verbosHttp).toContain('PUT')
})

Exemplo 6

Para testar se uma funç�o em particular gera uma exceç�o basta usar toThrow.

function conectaBancoDeDados(){
    throw new Error('N�o foi poss�vel conectar ao banco de dados')
}

test('conex�o com o banco de dados falha como esperado' ,()=>{
    expect(conectaBancoDeDados).toThrow(Error)
})

Tamb�m � poss�vel verificar a mensagem de erro, como demonstrado abaixo.

function conectaBancoDeDados(){
    throw new Error('N�o foi poss�vel conectar ao banco de dados')
}

test('conex�o com o banco de dados falha como esperado' ,()=>{
    expect(conectaBancoDeDados).toThrow('N�o foi poss�vel conectar ao banco de dados')
    expect(conectaBancoDeDados).toThrow(/dados/)
})

Funç�es de Mock

Vis�o geral

Funç�es de mock s�o funç�es que permitem criar m�dulos e funç�es falsas utilizadas para simular uma depend�ncia. Elas facilitam testar as ligaç�es no c�digo por substituir uma depend�ncia cuja implementaç�o seria invi�vel dentro do teste. O ato de mockar uma funç�o torna poss�vel capturar chamadas dessa funç�o (e seus par�metros) pelo c�digo sendo testado, permite capturar inst�ncias de funç�es construtoras quando implementadas usando new e tamb�m permitem a configuraç�o dos valores retornados para o c�digo sob teste.

Funç�es mock s�o criadas a partir da funç�o jest.fn() e podem ser configuradas para reproduzir o comportamento desejado.

Na pr�tica

Exemplo 1

Para ilustrar uma funç�o mock vamos tomar de exemplo a funç�o pagamentoMoedaEstrangeira que converte o valor da moeda de real para a desejada de acordo com o valor atualizado provido em uma API que � injetada na funç�o, a API retorna o valor da moeda em relaç�o ao real de acordo com o par�metro passado:

function pagamentoMoedaEstrangeira (tipoMoeda, valor, currency) {
  if (tipoMoeda === Currency.QUOTACAO_DOLAR) {
    valor *= currency.getQuotacaoDolar()
  } else if (tipoMoeda === Currency.QUOTACAO_EURO) {
    valor *= currency.getQuotacaoEuro()
  } else if (tipoMoeda === Currency.QUOTACAO_LIBRA) {
    valor *= currency.getQuotacaoLibra()
  } else {
    throw Error('moeda n�o dispon�vel')
  }
  return valor
}

module.exports = { pagamentoMoedaEstrangeira }

Ent�o conseguimos simular uma depend�ncia do c�digo sob teste sem aumentar muito a complexidade do c�digo de teste.

const { pagamentoMoedaEstrangeira } = require('../src/operacoes.js')

const mockCurrency = {}
mockCurrency.getQuotacaoDolar = jest.fn()
mockCurrency.getQuotacaoDolar.mockReturnValue(3)

test('chamar getQuotacaoDolar uma vez', () => {
  expect(pagamentoMoedaEstrangeira('dolar', 300, mockCurrency)).toBe(900)
})

Linha 3: Criamos o objeto que ir� portar a funç�o mock a ser criada.
Linha 4: � criada efetivamente a funç�o mock que ira ser usada dentro do teste.
Linha 5: Definido o valor de retorno que a funç�o getQuotacaoDolar ir� retornar quando for chamada, no caso 3

Exemplo 2

Todas as funç�es mock possuem a propriedade especial .mock, a qual armazena dados sobre como a funç�o foi chamada e o que ela retornou.

Usando a funç�o pagamentoMoedaEstrangeira como alvo do teste veja o exemplo:

test('chamar getCurrency uma vez', () => {
  expect(pagamentoMoedaEstrangeira('dolar', 300, mockCurrency)).toBe(900)
  // verifica se a funç�o foi chamada 1 vez
  expect(mockCurrency.getCurrency.mock.calls.length).toBe(1)

  // verifica se o primeiro argumento passado na primeira chamada foi zero
  expect(mockCurrency.getCurrency.mock.calls[0][0]).toBe(0)

  // verifica se o resultado da primeira chamada foi 3
  expect(mockCurrency.getCurrency.mock.results[0].value).toBe(3)    
})

A propriedade .mock tamb�m registra o valor de this para cada chamada.

A propriedade .calls de .mock possui uma matriz com as informaç�es de quantas vezes o mock foi chamado e quais atributos foram passados em cada chamada.

Linha 4: ilustra como � poss�vel saber quantas vezes a funç�o foi chamada pelo tamanho de calls.

expect(mockCurrency.getCurrency.mock.calls.length).toBe(1)
Linha 7: ilustra que podemos verificar qual atributo foi passado em uma chamada espec�fica de acordo com a posiç�o passada na matriz.

expect(mockCurrency.getCurrency.mock.calls[0][0]).toBe(0)
Linha 10: ilustra como podemos certificar qual foi o retorno da funç�o mock.

expect(mockCurrency.getCurrency.mock.results[0].value).toBe(3)

A sintaxe utilizada no exemplo anterior � a seguinte:

funcaoMock.mock.calls[call][arg]

Onde call � a vez em que a funç�o foi chamada e arg � o par�metro que foi passado naquela chamada.

Exemplo 3

Funç�es mock podem ser configuradas para injetar valores de teste dentro do c�digo sendo executado durante o teste:

const falso = jest.fn()

falso
  .mockReturnValueOnce('primeiro')
  .mockReturnValueOnce('segundo')
  .mockReturnValue('mais de uma vez')

console.log(falso(), falso(), falso(), falso())
// > 'primeiro', 'segundo', 'mais de uma vez', 'mais de uma vez'

Os valores de retorno de uma funç�o mock s�o definidos pelos m�todos .mockReturnValue() e .mockReturnValueOnce(), com a diferença que o segundo retorno s� ser� chamado uma vez. M�todos de retorno de valor ir�o seguir em execuç�o a ordem com a qual foram declaradas.

Linha 1: Criando o Mock
Linha 4: Definindo o valor que falso ir� retornar quando for executado na primeira vez
Linha 5: Definindo o valor que falso ir� retornar quando for executado na segunda vez
Linha 6: Definindo o valor de retorno que falso ir� retornar todas as outras vezes em que for chamado

Exemplo 4

Em certas situaç�es � necess�rio passar um m�dulo como depend�ncia para uma funç�o sendo testada mas n�o queremos que ela de fato execute essa depend�ncia toda vez que o teste for feito, como no caso de testar uma funç�o que interage com uma API por exemplo.

Nestes casos � poss�vel criar um m�dulo mock bem como definir resultados para funç�es desse m�dulo. A sintaxe para mockar um m�dulo e definir uma funç�o com retorno �:

const { modulo } = require('arquivo')

jest.mock('modulo')

modulo.funcao.mockResolvedValue("qualquer tipo de retorno")

Abaixo vemos um exemplo com uma funç�o de busca de usu�rio enviando um id para uma API e retorna o usu�rio encontrado:

const { api } = require('../helpers/usuarioAPI')
const buscarUsuario = id => api.encontrarPorId(id).then(resp => resp.data)

const usuarioRepository = {
  buscarUsuario: buscarUsuario
  // ... outras funç�es
}

module.exports = { usuarioRepository }

Para testar esse m�todo sem contatar diretamente a API (e portanto evitando um teste com uma depend�ncia externa) usamos a funç�o jest.mock() para automaticamente mockar o m�dulo usuarioRepository.

Em seguida declaramos um mockResolvedValue na funç�o encontrarPorId para que retorne sempre o mesmo valor quando for executada pela funç�o que estamos testando, nesse caso a funç�o buscarUsuario:

const { api } = require('../helpers/usuarioAPI')
const { usuarioRepository } = require('../src/usuarioRepository')

jest.mock('../helpers/usuarioAPI')

test('qualquer coisa', () => {
  const resposta = {data: {id: 1, nome: 'Jos�', idade: 42}}
  api.encontrarPorId.mockResolvedValue(resposta)
  usuarioRepository.buscarUsuario(12).then(
    usuario => expect(usuario).toEqual(resposta.data)
  )
})

Na Linha 1 requirimos o m�dulo usuarioAPI para a constante api. Na Linha 4 definimos que este m�dulo ser� substitu�do por um mock quando implementado dentro do contexto de teste. Na Linha 8 definimos um valor de retorno para quando entrarPorId resolver.

Exemplo 5

Existem casos em que � necess�rio ir al�m de especificar valores de retorno, sendo preciso substituir completamente a implementaç�o da funç�o mock. Isso pode se feito atrav�s de jest.fn:

UserModel.createUser = jest.fn( parametros => {
  console.log('um mock substituiu uma implementacao')
  return parametros
})

Com isso podemos simular comportamentos complexos de uma depend�ncia e realizar testes outrora invi�veis.

Outra forma de fazer mockar uma implementaç�o � atrav�s do m�todo mockImplementation em uma funç�o mock:

UserModel.createUser.mockImplementacion( parametros => {
  console.log('um mock substituiu uma implementacao')
  return parametros
})

Caso seja necess�rio recriar uma funç�o sendo chamada m�ltiplas vezes e produzir resultados diferentes, use mockImplementationOnce:

const UserModel.createUser = jest
  .fn()
  .mockImplementationOnce(param => param)
  .mockImplementationOnce(param => {})

Testes de C�digo Ass�ncrono

Quando h� c�digo rodando de forma ass�ncrona dentro de um teste, o Jest precisa saber quando o c�digo termina de ser testado antes de poder começar o pr�ximo teste. Jest possui diversas formas de fazer isso.

Vis�o geral

Por padr�o os testes em Jest completam assim que chegam ao fim de sua execuç�o, ou seja, se uma funç�o chamar uma callback, o teste completar� ao fim da execuç�o de dita funç�o, antes mesmo de chamar a callback.

O exemplo abaixo n�o funcionar�:

function buscarResultado (param) {
      return param('resultado')
    }
    
    test('callback da forma errada', () => {
      const callback = (dados) => {
        expect(dados).toBe('resultado')
      }
    
      buscarResultado(callback)
    })

Para garantir que o teste seja feito de forma adequada basta passar done como argumento da callback ao inv�s de passar uma funç�o com argumento vazio. Jest aguardar� at� que done seja chamado antes do fim de concluir o teste.

Abaixo a forma correta de testar callbacks:

function buscarResultado (param) {
      return param('resultado')
    }
    
    test('callback da forma certa', done => {
      const callback = (dados) => {
        expect(dados).toBe('resultado')
        done()
      }
    
      buscarResultado(callback)
    })

O c�digo acima � praticamente id�ntico ao anterior exceto na Linha 5 onde � passado done como par�metro e na Linha 8 com sua chamada.

Na pr�tica

Exemplo 1

Caso seu c�digo possua promises, h� uma forma mais simples de manejar testes ass�ncronos. Basta retornar uma promise de seu teste e o Jest ir� aguardar que essa promise resolva. Caso a promise seja rejeitada o teste falhar�.

Por exemplo, a funç�o lerArquivo importa a funç�o readFile e a transforma em uma promise ap�s uma r�pida validaç�o:

const { readFile } = require('fs')
    const { promisify } = require('util')
    
    function lerArquivo (path, options = {}) {
      if (!path || typeof path !== 'string') {
        return Promise.reject(new Error('path is incorrect or not defined'))
      }
    
      return promisify(readFile)(path, options)
    }
    
    module.exports = { lerArquivo }

Para test�-la criamos um pequeno index.html dentro da pasta files apenas com "hello world" escrito. Criamos o teste para a funç�o lerArquivo e implementamos um segundo .then com o nosso expect:

const { lerArquivo } = require('../helpers/arquivosManager')
    
    test('testando leitura de arquivo', () => {
      lerArquivo('./files/index.html')
        .then(buffer => buffer.toString('utf8'))
        .then(conteudo => expect(conteudo).toBe('hello world\n'))
    })

Na Linha 5 � feita a chamada da promise lerArquivo, na Linha 6 � feito a convers�o do resultado da promise para UTF-8 e na Linha 7 o teste � feito com o resultado dessa convers�o, que deve ser igual a 'hello world\n'.

Exemplo 2

Tamb�m � poss�vel usar o matcher .resolves e o Jest ir� esperar que a promise resolva. Se a promise for rejeitada o teste falhar�.

const { lerArquivo } = require('../helpers/arquivosManager')
    
    test('lendo arquivo', () => {
      expect(lerArquivo('./files/index.html')
        .then(buffer => buffer.toString('utf8')))
        .resolves.toEqual('hello world\n')
    })

Observe na Linha 5 que neste exemplo a promise � feita dentro do expect ao contr�rio do que foi feito no exemplo anterior. Na Linha 7 indicamos ao jest que a promise ira retornar 'hello world\n' quando resolver

Exemplo 5

Caso o esperado seja que a promise seja rejeitada basta usar o matcher .rejects. De forma an�loga ao .resolves, se a promise resolver o teste falhar�

const { lerArquivo } = require('../helpers/arquivosManager')
    
    test('lendo arquivo', () => {
      expect(lerArquivo('')).rejects.toBeDefined()
    })

Na Linha 4 � definido que a promise lerArquivo deve terminar em uma rejeiç�o ou o teste ir� falhar.

Teste unit�rio com Jest

Jest é um framework de teste unitário de código aberto em JavaScript criado pelo Facebook a partir do framework Jasmine. Jest é uma das ferramentas de teste unitário mais difundidas dentro da comunidade de JavaScript.

Vis�o Geral

Instalaç�o

yarn

npm

Configuraç�o

Escrevendo Testes

Vis�o geral

Na pr�tica

Exemplo 1

Exemplo 2

Exemplo 3

Exemplo 4

Exemplo 5

Exemplo 6

Funç�es de Mock

Vis�o geral

Na pr�tica

Exemplo 1

Exemplo 2

Exemplo 3

Exemplo 4

Exemplo 5

Testes de C�digo Ass�ncrono

Vis�o geral

Na pr�tica

Exemplo 1

Exemplo 2

Exemplo 5

Artigos relacionados