@equallyze/wally-cypress

Plugin Cypress para integração com a plataforma Wally de testes automatizados de acessibilidade digital.

📋 Índice

• Visão Geral
• Instalação
• Configuração
• Uso
• API
• Exemplos
• Fluxo de Funcionamento
• Troubleshooting

🎯 Visão Geral

O wally-cypress permite integrar seus testes E2E Cypress com a plataforma Wally para:

• ✅ Capturar páginas durante a execução dos testes
• ✅ Enviar HTML para análise automática de acessibilidade
• ✅ Gerar relatórios detalhados de conformidade (WCAG 2.1/2.2, ABNT NBR 17225, EAA)
• ✅ Integrar com pipelines CI/CD

Como funciona?

1. Início da execução: Plugin inicia uma sessão de navegação no Wally
2. Durante os testes: cy.accessibility('Nome da Página') captura e envia o HTML
3. Fim da execução: Sessão é finalizada e análise de acessibilidade é disparada
4. Resultado: Relatório disponível no dashboard Wally

📦 Instalação

# npm
npm install @equallyze/wally-cypress --save-dev

# yarn
yarn add @equallyze/wally-cypress --dev

# pnpm
pnpm add @equallyze/wally-cypress -D

Requisitos

• Node.js >= 18.0.0
• Cypress >= 12.0.0
• Conta no Wally com API Key

⚙️ Configuração

1. Configurar o Plugin (cypress.config.ts)

import { defineConfig } from 'cypress';
import { wallyPlugin } from '@equallyze/wally-cypress/plugin';

export default defineConfig({
  e2e: {
    baseUrl: 'https://seu-site.com',
    setupNodeEvents(on, config) {
      // Configuração do plugin Wally
      wallyPlugin(on, config, {
        apiKey: process.env.WALLY_API_KEY!,
        projectId: process.env.WALLY_PROJECT_ID!,
      });

      return config;
    },
  },
});

2. Importar Support Commands (cypress/support/e2e.ts)

import '@equallyze/wally-cypress/support';

3. Variáveis de Ambiente

Crie um arquivo .env ou configure no seu CI/CD:

WALLY_API_KEY=sua-api-key-aqui
WALLY_PROJECT_ID=id-do-projeto

Obtendo suas credenciais

1. Acesse wally.equallyze.com
2. Vá em Configurações > API Keys
3. Crie uma nova API Key
4. Copie o Project ID do projeto desejado

🚀 Uso

Uso Básico

describe('Testes de Acessibilidade', () => {
  it('deve verificar acessibilidade do fluxo de checkout', () => {
    // Navega para homepage
    cy.visit('/');
    cy.accessibility('Homepage'); // Captura para análise

    // Navega para produtos
    cy.get('[data-cy="products-link"]').click();
    cy.accessibility('Página de Produtos');

    // Adiciona ao carrinho
    cy.get('[data-cy="add-to-cart"]').first().click();
    cy.accessibility('Carrinho de Compras');

    // Checkout
    cy.get('[data-cy="checkout-btn"]').click();
    cy.accessibility('Checkout - Step 1');
  });
});

Múltiplos Specs

A sessão é gerenciada automaticamente durante toda a execução do Cypress:

// spec-1.cy.ts
describe('Homepage', () => {
  it('deve ser acessível', () => {
    cy.visit('/');
    cy.accessibility('Homepage');
  });
});

// spec-2.cy.ts
describe('Produtos', () => {
  it('lista deve ser acessível', () => {
    cy.visit('/produtos');
    cy.accessibility('Lista de Produtos');
  });
});
// Todas as páginas capturadas são enviadas na mesma sessão
// e analisadas juntas ao final da execução

📖 API

Comando Cypress

cy.accessibility(pageName)

Captura a página atual e envia para análise de acessibilidade.

| Parâmetro | Tipo | Descrição | | ---------- | -------- | ------------------------------------------------------ | | pageName | string | Nome descritivo da página (ex: "Homepage", "Checkout") |

Retorna: Chainable<WallyPage | null>

cy.accessibility('Formulário de Cadastro').then((page) => {
  expect(page?.title).to.equal('Formulário de Cadastro');
});

Nota: A sessão Wally é gerenciada automaticamente pelo plugin:

• Início: Hook before:run inicia a sessão
• Fim: Hook after:run finaliza e dispara a análise

Opções de Configuração

| Opção | Tipo | Default | Descrição | | --------------- | --------- | -------------- | ------------------------------------------------ | | apiKey | string | required | API Key da organização | | projectId | string | required | ID do projeto no Wally | | environment | string | 'production' | Ambiente: production, staging, development | | normId | string | - | ID da norma de acessibilidade | | qualityGateId | string | - | ID do quality gate | | timeout | number | 30000 | Timeout das requisições (ms) | | failOnError | boolean | false | Falhar teste em caso de erro |

💡 Exemplos

Integração com Login

describe('Área autenticada', () => {
  beforeEach(() => {
    cy.login(); // Seu comando de login
  });

  it('dashboard deve ser acessível', () => {
    cy.visit('/dashboard');
    cy.accessibility('Dashboard');

    cy.get('[data-cy="profile-menu"]').click();
    cy.accessibility('Menu de Perfil Aberto');
  });
});

Testando Modais e Overlays

it('modal de confirmação deve ser acessível', () => {
  cy.visit('/products');
  cy.accessibility('Lista de Produtos');

  // Abre modal
  cy.get('[data-cy="delete-btn"]').first().click();
  cy.get('[data-cy="confirm-modal"]').should('be.visible');

  // Captura com modal aberto
  cy.accessibility('Modal de Confirmação');

  // Fecha modal
  cy.get('[data-cy="cancel-btn"]').click();
});

CI/CD (GitHub Actions)

name: E2E Tests with Accessibility

on: [push, pull_request]

jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run Cypress tests
        run: npm run cy:run
        env:
          WALLY_API_KEY: ${{ secrets.WALLY_API_KEY }}
          WALLY_PROJECT_ID: ${{ secrets.WALLY_PROJECT_ID }}

🔄 Fluxo de Funcionamento

┌─────────────────────────────────────────────────────────────────┐
│                         CYPRESS TEST                             │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │  before:run    │→ │  Test Specs    │→ │  after:run     │     │
│  │  (init plugin) │  │  (captures)    │  │  (finish)      │     │
│  └────────────────┘  └────────────────┘  └────────────────┘     │
└──────────┬───────────────────┬────────────────────┬─────────────┘
           │                   │                    │
           ▼                   ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                      WALLY BACKEND API                           │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │ POST /sessions │  │ POST /pages    │  │ POST /finish   │     │
│  │ (create)       │  │ (upload HTML)  │  │ (analyze)      │     │
│  └────────────────┘  └────────────────┘  └────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
                    ┌────────────────────┐
                    │   WALLY ANALYSIS   │
                    │ (WCAG/NBR/EAA)     │
                    └────────────────────┘
                                │
                                ▼
                    ┌────────────────────┐
                    │  WALLY DASHBOARD   │
                    │  (Relatórios)      │
                    └────────────────────┘

🐛 Troubleshooting

Erro: "apiKey é obrigatório"

Certifique-se de que a variável de ambiente está configurada:

# Teste local
export WALLY_API_KEY=sua-api-key
npx cypress run

Erro: "Falha ao validar API Key"

1. Verifique se a API Key está correta
2. Confira se a API Key não expirou
3. Verifique conectividade com a API Wally

Páginas não aparecem no relatório

1. Verifique se cy.accessibility() está sendo chamado
2. Confira os logs do Cypress para erros
3. Ative verbose: true na configuração

Sessão não é finalizada

O plugin finaliza automaticamente no hook after:run. Verifique se:

1. O Cypress está finalizando corretamente (sem crash)
2. A configuração do plugin está correta no cypress.config.ts
3. Não há erros de rede/timeout nos logs

📄 Licença

UNLICENSED - Software Proprietário © Equallyze

Este software é de propriedade exclusiva da Equallyze. Todos os direitos reservados.

O uso deste pacote está restrito a:

• ✅ Clientes com licença ativa da plataforma Wally
• ✅ Projetos autorizados pela Equallyze
• ❌ Uso comercial não autorizado é proibido
• ❌ Redistribuição não é permitida

Para mais informações sobre licenciamento, entre em contato: [email protected]

�️ Desenvolvimento

Pré-requisitos

• Node.js >= 18.0.0
• npm ou pnpm

Setup local

# Clone o repositório
git clone https://gitlab.com/ucloud-tech/wally/wally-cypress.git
cd wally-cypress

# Instale dependências
npm install

# Build
npm run build

# Rodar testes
npm test

# Rodar testes com cobertura
npm run test:coverage

# Lint
npm run lint

# Typecheck
npm run typecheck

Hooks de Pre-commit

O projeto usa Husky + lint-staged para garantir qualidade do código:

• pre-commit: Executa ESLint e Prettier nos arquivos staged
• pre-push: Executa typecheck e testes com cobertura mínima de 50%

Scripts disponíveis

| Script | Descrição | | ----------------------- | --------------------------------- | | npm run build | Compila o projeto | | npm run dev | Build em modo watch | | npm test | Executa testes | | npm run test:coverage | Testes com relatório de cobertura | | npm run lint | Executa ESLint | | npm run lint:fix | ESLint com auto-fix | | npm run format | Formata código com Prettier | | npm run typecheck | Verifica tipos TypeScript | | npm run validate | Executa lint, typecheck e testes |

Cobertura de Testes

O projeto requer cobertura mínima de 50% em:

• Branches
• Functions
• Lines
• Statements

🔗 Links

• Documentação Wally
• Dashboard Wally
• Suporte