Clarity Design System

Design System React + TypeScript + Vite com componentes reutilizáveis.

Tecnologias

• Repositório: clarity-design-system
• React 18 com TypeScript
• Vite para build e desenvolvimento
• Storybook para documentação de componentes
• Vitest para testes
• ESLint para linting

Instalação

git clone https://git-codecommit.us-east-2.amazonaws.com/v1/repos/clarity-design-system
cd clarity-design-system
npm install

🛠️ Scripts Disponíveis

Desenvolvimento

• npm run dev - Inicia o servidor de desenvolvimento

  • Executa o Vite em modo desenvolvimento
  • Hot reload automático
  • Disponível em: http://localhost:5173

• npm run dev:check - Desenvolvimento com verificação de tipos

  • Executa o Vite + verificação de TypeScript em paralelo
  • Mostra erros de tipos em tempo real

Build e Deploy

• npm run build - Gera build de produção

  • Verifica tipos com TypeScript
  • Gera arquivos otimizados na pasta dist/

• npm run preview - Visualiza o build de produção

  • Serve os arquivos da pasta dist/
  • Útil para testar o build antes do deploy

Qualidade de Código

• npm run lint - Executa o ESLint

  • Verifica problemas de código e estilo
  • Segue as regras configuradas no eslint.config.js

• npm run type-check - Verifica tipos TypeScript

  • Executa verificação completa de tipos
  • Não gera arquivos, apenas valida

Testes

• npm test ou npm run test - Executa testes em modo watch

  • Reexecuta testes automaticamente quando arquivos mudam
  • Ideal para desenvolvimento

• npm run test:run - Executa todos os testes uma vez

  • Execução única de todos os testes
  • Ideal para CI/CD e verificações rápidas

• npm run test:ui - Interface gráfica dos testes

  • Abre uma interface web para visualizar testes
  • Disponível em: http://localhost:51204
  • Permite executar testes específicos

• npm run test:coverage - Testes com relatório de cobertura

  • Executa todos os testes
  • Gera relatório de cobertura de código
  • Mostra quais linhas não estão sendo testadas

• npm run test:watch - Modo watch explícito

  • Mesmo comportamento do npm test
  • Útil para scripts automatizados

🧪 Configuração de Testes

O projeto usa Vitest como framework de testes com as seguintes ferramentas:

• Vitest - Framework de testes rápido
• @testing-library/react - Utilitários para testar componentes React
• @testing-library/jest-dom - Matchers adicionais para DOM
• @testing-library/user-event - Simulação de eventos do usuário
• jsdom - Ambiente DOM para testes
• Axios Mock - Mock automático para requisições HTTP

Estrutura de Testes

🌐 Mock do Axios

O projeto inclui configuração automática de mock para o Axios. Todas as requisições HTTP são automaticamente mockadas durante os testes.

Configuração Automática

O mock está configurado no arquivo src/test/setup.ts e inclui:

• ✅ Todos os métodos HTTP (get, post, put, delete, patch)
• ✅ Suporte a axios.create() para instâncias customizadas
• ✅ Mock dos interceptors (request e response)
• ✅ Retorna promises resolvidas por padrão

Exemplos de Uso nos Testes

1. Mock de Requisição GET Simples

import { render, screen, waitFor } from '@testing-library/react'
import { vi } from 'vitest'
import axios from 'axios'
import UserProfile from './UserProfile'

test('should display user name', async () => {
  // Arrange: Mock da resposta da API
  const mockUser = { id: 1, name: 'João Silva', email: '[email protected]' }
  vi.mocked(axios.get).mockResolvedValueOnce({ data: mockUser })

  // Act: Renderizar componente
  render(<UserProfile userId={1} />)

  // Assert: Verificar se o nome aparece na tela
  await waitFor(() => {
    expect(screen.getByText('João Silva')).toBeInTheDocument()
  })

  // Verificar se a requisição foi feita corretamente
  expect(axios.get).toHaveBeenCalledWith('/api/users/1')
})

2. Mock de Requisição POST

import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import { vi } from 'vitest'
import axios from 'axios'
import CreateUserForm from './CreateUserForm'

test('should create user successfully', async () => {
  // Arrange: Mock da resposta de criação
  const newUser = { id: 2, name: 'Maria Santos' }
  vi.mocked(axios.post).mockResolvedValueOnce({ data: newUser })

  // Act: Renderizar e preencher formulário
  render(<CreateUserForm />)
  fireEvent.change(screen.getByLabelText(/nome/i), {
    target: { value: 'Maria Santos' }
  })
  fireEvent.click(screen.getByRole('button', { name: /criar/i }))

  // Assert: Verificar sucesso
  await waitFor(() => {
    expect(screen.getByText(/usuário criado com sucesso/i)).toBeInTheDocument()
  })

  expect(axios.post).toHaveBeenCalledWith('/api/users', {
    name: 'Maria Santos'
  })
})

3. Mock de Erro de API

import { render, screen, waitFor } from '@testing-library/react'
import { vi } from 'vitest'
import axios from 'axios'
import UserList from './UserList'

test('should handle API error gracefully', async () => {
  // Arrange: Mock de erro
  const errorMessage = 'Network Error'
  vi.mocked(axios.get).mockRejectedValueOnce(new Error(errorMessage))

  // Act: Renderizar componente
  render(<UserList />)

  // Assert: Verificar mensagem de erro
  await waitFor(() => {
    expect(screen.getByText(/erro ao carregar usuários/i)).toBeInTheDocument()
  })
})

4. Mock de Múltiplas Requisições

import { render, screen, waitFor } from '@testing-library/react'
import { vi } from 'vitest'
import axios from 'axios'
import Dashboard from './Dashboard'

test('should load dashboard data', async () => {
  // Arrange: Mock de múltiplas APIs
  const mockUsers = [{ id: 1, name: 'João' }]
  const mockStats = { total: 100, active: 85 }
  
  vi.mocked(axios.get)
    .mockResolvedValueOnce({ data: mockUsers })  // Primeira chamada
    .mockResolvedValueOnce({ data: mockStats })  // Segunda chamada

  // Act: Renderizar dashboard
  render(<Dashboard />)

  // Assert: Verificar dados carregados
  await waitFor(() => {
    expect(screen.getByText('João')).toBeInTheDocument()
    expect(screen.getByText('Total: 100')).toBeInTheDocument()
  })

  expect(axios.get).toHaveBeenCalledTimes(2)
  expect(axios.get).toHaveBeenNthCalledWith(1, '/api/users')
  expect(axios.get).toHaveBeenNthCalledWith(2, '/api/stats')
})

5. Mock de Instância Customizada do Axios

import { render, screen, waitFor } from '@testing-library/react'
import { vi } from 'vitest'
import axios from 'axios'
import ApiService from '../services/ApiService'
import ProductList from './ProductList'

test('should use custom axios instance', async () => {
  // Arrange: Mock da instância customizada
  const mockProducts = [{ id: 1, name: 'Produto A' }]
  const mockAxiosInstance = {
    get: vi.fn().mockResolvedValue({ data: mockProducts })
  }
  vi.mocked(axios.create).mockReturnValue(mockAxiosInstance as any)

  // Act: Renderizar componente que usa ApiService
  render(<ProductList />)

  // Assert: Verificar se usou a instância correta
  await waitFor(() => {
    expect(screen.getByText('Produto A')).toBeInTheDocument()
  })

  expect(mockAxiosInstance.get).toHaveBeenCalledWith('/products')
})

6. Mock de Interceptors

import { vi } from 'vitest'
import axios from 'axios'
import { setupAuthInterceptor } from '../services/auth'

test('should setup auth interceptor', () => {
  // Arrange: Mock dos interceptors
  const mockInterceptors = {
    request: { use: vi.fn() },
    response: { use: vi.fn() }
  }
  vi.mocked(axios.interceptors).request = mockInterceptors.request as any
  vi.mocked(axios.interceptors).response = mockInterceptors.response as any

  // Act: Configurar interceptor
  setupAuthInterceptor()

  // Assert: Verificar se foi configurado
  expect(mockInterceptors.request.use).toHaveBeenCalled()
  expect(mockInterceptors.response.use).toHaveBeenCalled()
})

Dicas Importantes

1. Reset entre testes: O mock é automaticamente resetado entre testes
2. Verificar chamadas: Use expect(axios.get).toHaveBeenCalledWith() para verificar parâmetros
3. Múltiplas respostas: Use .mockResolvedValueOnce() para diferentes respostas em sequência
4. Erros: Use .mockRejectedValueOnce() para simular erros de rede
5. Instâncias: O mock também funciona com axios.create()

📁 Estrutura do Projeto

🔧 Tecnologias

• React 19 - Biblioteca para interfaces
• TypeScript - Superset tipado do JavaScript
• Vite - Build tool e dev server
• Vitest - Framework de testes
• ESLint - Linter para qualidade de código
• Bootstrap - Framework CSS
• Axios - Cliente HTTP (com mock automático nos testes)

📝 Comandos Úteis

🚀 Desenvolvimento

# Desenvolvimento (ambiente development)
npm run dev

# Desenvolvimento com verificação de tipos em watch
npm run dev:check

# Desenvolvimento (ambiente homologação)
npm run dev:hml

# Desenvolvimento (ambiente produção)
npm run dev:prod

🏗️ Build para Deploy

# Build para desenvolvimento (saída: dist/dev/)
npm run build:dev

# Build para homologação (saída: dist/hml/)
npm run build:hml

# Build para produção (saída: dist/prod/)
npm run build:prod

# Build padrão (desenvolvimento)
npm run build

👀 Preview dos Builds

# Preview do build de desenvolvimento
npm run preview:dev

# Preview do build de homologação
npm run preview:hml

# Preview do build de produção
npm run preview:prod

# Preview padrão
npm run preview

🧪 Testes

# Executar testes
npm run test

# Executar testes com interface gráfica
npm run test:ui

# Executar testes uma vez (CI/CD)
npm run test:run

# Executar testes com cobertura
npm run test:coverage

# Executar testes em modo watch
npm run test:watch

# Executar testes específicos
npm test -- UserProfile.test.tsx

🔍 Qualidade de Código

# Verificar ESLint
npm run lint

# Verificar tipos TypeScript
npm run type-check

# Verificação completa
npm run lint && npm run type-check

🌍 Ambientes Disponíveis

| Ambiente | Servidor API | Saída do Build | |----------|--------------|----------------| | Development | dev.bethebeth.com.br | dist/dev/ | | Homolog | hml.bethconecta.com.br | dist/hml/ | | Production | apps.bethconecta.com.br | dist/prod/ |

🚀 Fluxo Completo de Deploy

# Para desenvolvimento
npm run build:dev && npm run preview:dev

# Para homologação
npm run build:hml && npm run preview:hml

# Para produção
npm run build:prod && npm run preview:prod