Simplificando a integração contínua com Cypress e GitHub Actions

“Designed by vectorjuice / Freepik”

A atuação da pessoa que testa aplicações é bem abrangente num time de desenvolvimento de software. Um desafio que superei recentemente foi iniciar um projeto do zero utilizando o Cypress, versionando o código no GitHub e utilizando o GitHub Actions para configurar uma integração contínua a cada submissão do código para a branch principal.

Atuando com qualidade de software e testes percebi a importância e a necessidade cada vez maior dos testes codificados não estarem somente na minha máquina e os motivos que me levaram a buscar entender mais sobre o assunto tem sido:

1. Maior aproximação da codificação;
2. Feedbacks rápidos de forma antecipada;
3. Maior confiança ao trabalhar no projeto, sabendo que há uma bateria de testes executada a cada pull request.

Com isso, criei um passo a passo que me ajudou a superar esse desafio e espero que te ajude também a entender como criar um projeto do zero, versioná-lo, obtendo feedbacks rápidos por meio de uma pipeline e outras formas de notificação!

Os passos estão divididos da seguinte forma:

Parte 1 — Setup do framework de testes Cypress.io

Parte 2— Configuração do Repositório no GitHub

Parte 3— Comandos do git

Parte 4— Configurando o GitHub Actions

Parte 5 — Notificação via Discord

Obs: Foi utilizado o sistema operacional Linux para realizar o passo a passo e alguns dos comandos foram executados via terminal.

Parte 1 — Setup do framework de testes Cypress.io

Com o terminal aberto, criar pasta em local de sua preferência

mkdir nome-da-pasta

Acessar pasta local

cd nome-da-pasta

Iniciar o git para poder versionar o código

git init

Abrir IDE de sua preferência (utilizei VSCode)

code .

Criar arquivo .gitignore para o git não versionar determinados arquivos

touch .gitignore

Armazenar as seguintes informações dento do arquivo .gitignore

.DS_Store
cypress.env.json
cypress/screenshots/
cypress/videos/
node_modules/

node e npm são pré -requisitos. Segue o comando para listar as versões instaladas. Caso contrário é necessária a instalação dos mesmos

node -v && npm -v

Iniciar projeto npm que cria o arquivo package.json, onde serão listadas as dependências, scripts, e outras informações do projeto

npm init -y

Instalar o Cypress, o qual é baixado na pasta node_modules/ e é criado o arquivo package-lock.json com as versões das dependências

npm install cypress --save-dev

Abrir o Cypress pela primeira vez com a aplicação electron — versão desktop do Chrome com exemplos. É também criada a estrutura automaticamente do projeto com o arquivo cypress.json e o diretório cypress/ com os sub-diretórios fixtures/, integration/, plugins/ e support/

npx cypress open

Parte 2 — Configuração do Repositório no GitHub

Para prosseguir com os passos é necessário ter uma conta no GitHub e você pode criá-la aqui.

Para versionar o código no GitHub é necessário criar um repositório em seu perfil

Creating a new repository

Preencha os campos obrigatórios. Pra facilitar o processo deixei marcadas as opções de “Add a README file” e “Choose a license”

Form to create a new repository

Com o projeto criado remotamente no GitHub é necessário estabelecer a ligação entre o repositório local e o remoto. O objetivo disso é sincronizar os ambientes e enviar as alterações da máquina local para o GitHub.

Parte 3 — Comandos do git

Com o projeto configurado basta adicionar as alterações localmente para o git rastreá-las (arquivos adicionados ao .gitignore não serão rastreados)

git add .

Realizar o commit das alterações

git commit -m “aqui vai um resumo da alteração submetida”

Configurar repositório remoto para que as alterações sejam recebidas do repositório local

git remote add origin https://github.com/seu-usuario/seu-projeto.git

Enviar as alterações do repositório local para o remoto

git push origin main

Parte 4 — Configurando o GitHub Actions

No arquivo package.json há um npm script que foi renomeado para receber o comando abaixo e executar os testes em modo headless, uma vez que os executores em serviços de integração contínua normalmente não possuem um display para a abertura do navegador.

"scripts": {
  "test": "cypress run"
}

Configurar GitHub Actions com pipeline como código dentro do projeto criado

Setting the Github Actions

Selecionar a opção de configurar um novo workflow e substituir o conteúdo do arquivo a ser criado no diretório .github/workflows/main.yml com o seguinte conteúdo para executar em um container docker os testes contidos na pasta integration/examples/. Foi escolhida esse formato e há diversas outras personalizações básicas, disponíveis na documentação.

name: Cypress Tests using Cypress Docker Image
on: [push]
jobs:
 cypress-run:
 runs-on: ubuntu-latest
 container: cypress/browsers:node12.18.3-chrome87-ff82
 steps:
 — name: Checkout
 uses: actions/checkout@v2
# Install NPM dependencies, cache them correctly
 # and run all Cypress tests
 — name: Cypress run
 uses: cypress-io/github-action@v2
 with:
 # Specify Browser since container image is compile with Firefox
 browser: chrome

Sabendo-se que na instalação do Cypress há uma pasta com diversos exemplos, deixei apenas um arquivo ativo para fins de teste. Assim que há o push para a branch principal, a pipeline é disparada.

General view of the job running through the pipeline

Abrindo o job específico de testes, podemos ver os testes sendo executados no modo headless.

Specific view of the job running the tests on headless mode

Parte 5 — Notificação via Discord

Além de criar o projeto do zero, versionar o código adicionando a um repositório remoto e configurando o GitHub Actions, ainda foi possível configurar uma ferramenta como Discord para receber as notificações da pipeline.

Para prosseguir com os passos é necessário ter uma conta no Discord e você pode criá-la aqui.

Criar um canal específico para o recebimento das notificações

Create a channel

Nomear o canal de acordo com sua preferência

Create a channel

Acessar a opção de Editar canal

Edit a channel

Clicar em “Integrações” para configurar um Webhook

Create a Webhook

Criar o Webhook para gerar o link para integração com o repositório remoto

Create a Webhook

Acessar as configurações de Webhooks dentro das configurações do projeto remoto no GitHub para adicionar o link gerado pelo Discord ao campo de “Payload URL”. É recomendado pelo suporte do Discord adicionar /github ao final do link para melhor disposição das notificações

Com a integração finalizada, um push para a branch main dispara a pipeline e agora é possível receber a notificação de forma simples, como a seguir:

Discord notification

O código do projeto no GitHub está disponível aqui.

Conclusão

As práticas vistas durante esse experimento acarretam em maior segurança e feedback rápido quando mudanças locais são enviadas para um repositório remoto, possibilitando a correção o mais rápido possível, antes de tais modificações impactarem usuários do produto sendo desenvolvido.

Agradeço o apoio de Walmyr Filho na implementação do projeto e revisão deste artigo.

Referências

JavaScript End to End Testing Framework

GitHub: Where the world builds software

Features * GitHub Actions

Por quê integração contínua é tão importante?

GitHub Actions | Cypress Documentation

https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks

Git

Visual Studio Code - Code Editing. Redefined