) {
return <>{children(data)};
}
```
***
## Checklist TypeScript
[Seção intitulada “Checklist TypeScript”](#checklist-typescript)
Antes de commitar código:
* [ ] Nenhum uso de `any` (exceto casos extremos justificados)
* [ ] Todos os tipos exportados estão documentados
* [ ] Try-catch em todas operações assíncronas
* [ ] Erros tipados adequadamente
* [ ] Type guards onde necessário
* [ ] Uso de utility types quando apropriado
* [ ] Interfaces prefiram `readonly` onde aplicável
* [ ] Discriminated unions para estados complexos
* [ ] Exhaustive checking em switches
* [ ] Props de componentes totalmente tipadas
***
## Erros Comuns a Evitar
[Seção intitulada “Erros Comuns a Evitar”](#erros-comuns-a-evitar)
### ❌ NUNCA faça
[Seção intitulada “❌ NUNCA faça”](#-nunca-faça)
```typescript
// 1. Usar any
const data: any = fetchData();
// 2. Type assertion desnecessário
const user = data as User; // Perigoso se data não for User
// 3. Non-null assertion sem garantia
const value = possiblyNull!; // Pode quebrar em runtime
// 4. Ignorar erros
try {
await operation();
} catch {} // Silenciar erro
// 5. Tipos muito amplos
function process(data: object) {} // object é muito genérico
// 6. Mutação de readonly
function modify(arr: readonly string[]) {
arr.push("new"); // Erro!
}
```
### ✅ SEMPRE faça
[Seção intitulada “✅ SEMPRE faça”](#-sempre-faça)
```typescript
// 1. Type guards
if (isUser(data)) {
Logger.debug(data.email);
}
// 2. Validação adequada
const user = validateUser(data); // Lança erro se inválido
// 3. Null checking
const value = possiblyNull ?? defaultValue;
// 4. Log apropriado
try {
await operation();
} catch (error) {
logger.error("Operation failed", { error });
throw error;
}
// 5. Tipos específicos
interface ProcessData {
id: string;
value: number;
}
function process(data: ProcessData) {}
// 6. Criar nova array
function modify(arr: readonly string[]): string[] {
return [...arr, "new"];
}
```
***
## Scripts e Comandos
[Seção intitulada “Scripts e Comandos”](#scripts-e-comandos)
### Scripts (root)
[Seção intitulada “Scripts (root)”](#scripts-root)
```bash
npm run build # Build todos workspaces
npm run lint # Biome lint + typecheck
npm run test # Rodar testes
npm run serve:demo # Dev apontando para stg
```
### Ambientes
[Seção intitulada “Ambientes”](#ambientes)
* **local** - desenvolvimento local
* **test/dev** - ambiente de desenvolvimento
* **demo/stg** - staging
* **live/prd** - produção
***
## EZ4 - Infrastructure as Code
[Seção intitulada “EZ4 - Infrastructure as Code”](#ez4---infrastructure-as-code)
O projeto usa **[EZ4](https://github.com/sbalmt/ez4)** para deploy na AWS.
### Pacotes EZ4 usados
[Seção intitulada “Pacotes EZ4 usados”](#pacotes-ez4-usados)
* `@ez4/common` - Tipos e utilitários
* `@ez4/utils` - Funções gerais
* `@ez4/project` - Config de projeto
* `@ez4/aws-bucket` - S3 Bucket
* `@ez4/aws-cloudfront` - CloudFront (CDN)
* `@ez4/distribution` - Contrato de distribuição
***
## ✅ Checklist Antes de Implementar
[Seção intitulada “✅ Checklist Antes de Implementar”](#-checklist-antes-de-implementar)
### IMPORTANTE
[Seção intitulada “IMPORTANTE”](#importante)
Este documento contém diretrizes obrigatórias. Claude Code deve seguir TODOS os padrões.
### Antes de QUALQUER implementação
[Seção intitulada “Antes de QUALQUER implementação”](#antes-de-qualquer-implementação)
* [ ] Li arquivos relevantes na pasta?
* [ ] Identifiquei componentes/código similar?
* [ ] Identifiquei padrões de nomenclatura?
* [ ] Identifiquei estrutura de código?
* [ ] Mostrei exemplos do código existente?
* [ ] Recebi confirmação?
### Durante implementação
[Seção intitulada “Durante implementação”](#durante-implementação)
* [ ] Seguindo EXATAMENTE os padrões identificados?
* [ ] Reutilizando código ao invés de duplicar?
* [ ] TypeScript com tipagem completa?
* [ ] Usando Biome (não ESLint/Prettier)?
* [ ] Usando TailwindCSS (não CSS modules)?
* [ ] Usando bibliotecas corretas (Vitest, não Jest)?
* [ ] Nomenclatura correta?
* [ ] Componentes base: `[pasta]/component.tsx`?
* [ ] Features: `[feature]/kebab-case.tsx`?
* [ ] Stores com devtools + version?
* [ ] Usando shallow em Zustand?
***
## O QUE NUNCA FAZER
[Seção intitulada “O QUE NUNCA FAZER”](#o-que-nunca-fazer)
* ❌ Nunca use ESLint ou Prettier (use Biome)
* ❌ Nunca use Jest (use Vitest)
* ❌ Nunca use CSS modules (use Tailwind)
* ❌ Nunca use moment.js/dayjs (use date-fns)
* ❌ Nunca implemente sem analisar código existente
* ❌ Nunca duplique código que já existe
* ❌ Nunca crie padrões novos sem justificativa
* ❌ Nunca use Context API (use Zustand)
* ❌ Nunca faça fetch direto (use React Query)
* ❌ Nunca commite código sem tipagem TypeScript
* ❌ Nunca commite secrets/API keys
* ❌ Nunca crie store Zustand sem devtools + version
* ❌ Nunca use múltiplos valores Zustand sem shallow
* ❌ Nunca ignore a estrutura de pastas do projeto
***
## Perguntas Frequentes
[Seção intitulada “Perguntas Frequentes”](#perguntas-frequentes)
**P: Onde criar componentes reutilizáveis?** R: Em `src/components/[categoria]/component.tsx`
**P: Onde criar features complexas?** R: Em `src/features/[feature-name]/`
**P: Como nomear arquivos de componentes?** R: Componentes base: `component.tsx`. Features: `kebab-case.tsx`
**P: Onde ficam as stores Zustand?** R: Dentro das features: `src/features/[feature]/store/`
**P: Como usar ícones?** R: Lucide React (já instalado)
**P: Como estilizar?** R: TailwindCSS + cva para variantes
***
## Referências
[Seção intitulada “Referências”](#referências)
* [EZ4 GitHub](https://github.com/sbalmt/ez4)
* [Radix UI](https://www.radix-ui.com/)
* [shadcn/ui](https://ui.shadcn.com/)
* [TanStack Query](https://tanstack.com/query/latest)
* [Zustand](https://docs.pmnd.rs/zustand)
* [Biome](https://biomejs.dev/)
* [Vitest](https://vitest.dev/)
* [Doppler](https://www.doppler.com/)
* [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
* [TypeScript Deep Dive](https://basarat.gitbook.io/typescript/)
* [Type Challenges](https://github.com/type-challenges/type-challenges)
* [Total TypeScript](https://www.totaltypescript.com/)
# Internacionalização (i18n)
> Guia completo para implementação de internacionalização na plataforma Gaio.
* [Introdução](#introdu%C3%A7%C3%A3o)
* [Arquitetura](#arquitetura)
* [Hooks e Funções](#hooks-e-fun%C3%A7%C3%B5es)
* [Padrões de Tradução](#padr%C3%B5es-de-tradu%C3%A7%C3%A3o)
* [Namespaces](#namespaces)
* [Integração com Zod](#integra%C3%A7%C3%A3o-com-zod)
* [Pluralização e Interpolação](#pluraliza%C3%A7%C3%A3o-e-interpola%C3%A7%C3%A3o)
* [Melhores Práticas de Interpolação](#melhores-pr%C3%A1ticas-de-interpola%C3%A7%C3%A3o)
* [Formatação HTML em Traduções](#formata%C3%A7%C3%A3o-html-em-tradu%C3%A7%C3%B5es)
* [Caching com localStorage](#caching-com-localstorage)
* [Seletor de Idioma](#seletor-de-idioma)
* [CLI e Extração](#cli-e-extra%C3%A7%C3%A3o)
* [Validação i18n (CI/CD)](#valida%C3%A7%C3%A3o-i18n-cicd)
* [Testes](#testes)
* [Anti-patterns](#anti-patterns)
* [Tipagem TypeScript (Intellisense)](#tipagem-typescript-intellisense)
***
## Introdução
[Seção intitulada “Introdução”](#introdução)
### Stack
[Seção intitulada “Stack”](#stack)
| Biblioteca | Versão | Propósito |
| ---------------------------------- | ------ | --------------------------- |
| `i18next` | 25.x | Core de internacionalização |
| `react-i18next` | 16.x | Bindings React |
| `i18next-browser-languagedetector` | 8.x | Detecção automática |
| `i18next-chained-backend` | 5.x | Múltiplos backends |
| `i18next-localstorage-backend` | 4.x | Cache em localStorage |
| `i18next-resources-to-backend` | 1.x | Converter recursos inline |
| `i18next-cli` | 1.x | Extração de strings (CLI) |
### Idiomas Suportados
[Seção intitulada “Idiomas Suportados”](#idiomas-suportados)
| Código | Nome | Status |
| ------- | ------------------ | -------- |
| `pt-BR` | Português (Brasil) | Fonte |
| `en` | English | Tradução |
### Arquitetura
[Seção intitulada “Arquitetura”](#arquitetura)
```plaintext
┌─────────────────────────────────────────────────────────────┐
│ @gaio/i18n │
│ (Package dedicado para internacionalização) │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌───────────┐ ┌───────────────┐
│ I18nProvider │ │ useT │ │ zodMessages │
│ (Wrapper App) │ │ (Hook) │ │ (Validação) │
└─────────────────┘ └───────────┘ └───────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ locales/ │
│ pt-BR/common.json │ en/common.json │ ... │
└─────────────────────────────────────────────────────────────┘
```
### Imports Padrão
[Seção intitulada “Imports Padrão”](#imports-padrão)
O package é dividido em dois módulos:
```typescript
// ============================================
// @gaio/i18n/core - SEM dependência de React
// Use em: utils, services, schemas Zod, constantes
// ============================================
import {
i18n,
zodMessages,
SUPPORTED_LOCALES,
LOCALE_LABELS,
clearI18nCache,
getCacheVersion,
} from "@gaio/i18n/core";
// ============================================
// @gaio/i18n/react - COM dependência de React
// Use em: componentes, hooks, providers
// ============================================
import { I18nProvider, useT, useLocale, changeLocale } from "@gaio/i18n/react";
// Componente Trans (re-export do react-i18next)
import { Trans } from "@gaio/i18n/react";
```
**Quando usar cada um:**
| Módulo | Uso | Exemplos |
| ------------------ | ------------------ | ---------------------------------------- |
| `@gaio/i18n/core` | Arquivos sem React | Schemas Zod, utils, services, constantes |
| `@gaio/i18n/react` | Componentes React | Hooks, Provider, componentes UI |
***
## Arquitetura
[Seção intitulada “Arquitetura”](#arquitetura-1)
### Estrutura do Package
[Seção intitulada “Estrutura do Package”](#estrutura-do-package)
```plaintext
packages/i18n/
├── package.json
├── tsconfig.json
├── i18next.config.ts
└── src/
├── core/ # @gaio/i18n/core (sem React)
│ ├── index.ts # Exports: i18n, zodMessages, constantes, cache utils
│ ├── constants.ts # SUPPORTED_LOCALES, NAMESPACES
│ ├── config.ts # Setup i18next com ChainedBackend
│ └── validation.ts # zodMessages
│
├── react/ # @gaio/i18n/react (com React)
│ ├── index.ts # Exports: Provider, hooks, Trans
│ ├── provider.tsx # I18nProvider
│ └── hooks.ts # useT, useLocale, changeLocale
│
├── types/ # Tipagem TypeScript
│ └── resources.d.ts # Declaração para intellisense
│
└── locales/ # Traduções
├── pt-BR/
│ ├── index.ts
│ ├── common.json
│ ├── validation.json
│ ├── errors.json
│ ├── auth.json
│ ├── inbox.json
│ ├── workflows.json
│ └── settings.json
└── en/
└── ... (mesmos arquivos)
```
### Exports do Package
[Seção intitulada “Exports do Package”](#exports-do-package)
package.json
```json
{
"exports": {
"./core": "./src/core/index.ts",
"./react": "./src/react/index.ts"
}
}
```
### Integração com Console
[Seção intitulada “Integração com Console”](#integração-com-console)
O `I18nProvider` deve ser o provider mais externo na aplicação:
packages/console/src/providers.tsx
```tsx
import { I18nProvider } from "@gaio/i18n/react";
export function AppProviders({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
***
## Hooks e Funções
[Seção intitulada “Hooks e Funções”](#hooks-e-funções)
### useT
[Seção intitulada “useT”](#uset)
Hook principal para acessar traduções. Wrapper do `useTranslation` do react-i18next.
```typescript
import { useT } from '@gaio/i18n/react';
function MyComponent() {
const { t } = useT();
return ;
}
```
#### Com Namespace Específico
[Seção intitulada “Com Namespace Específico”](#com-namespace-específico)
```typescript
// Namespace único
const { t } = useT("validation");
t("required"); // validation:required
// Múltiplos namespaces
const { t } = useT(["common", "validation"]);
t("common:actions.save");
t("validation:required");
```
#### Retorno do useT
[Seção intitulada “Retorno do useT”](#retorno-do-uset)
| Propriedade | Tipo | Descrição |
| ----------- | --------------------------- | -------------------------- |
| `t` | `(key, options?) => string` | Função de tradução |
| `i18n` | `i18n` | Instância i18next |
| `ready` | `boolean` | Se traduções estão prontas |
### useLocale
[Seção intitulada “useLocale”](#uselocale)
Hook para obter o idioma atual.
**Localização:** `@gaio/i18n/react`
```typescript
import { useLocale } from '@gaio/i18n/react';
function LanguageIndicator() {
const locale = useLocale(); // 'pt-BR' | 'en-US'
return Idioma: {locale};
}
```
### changeLocale
[Seção intitulada “changeLocale”](#changelocale)
Função para trocar o idioma programaticamente.
**Localização:** `@gaio/i18n/react`
```typescript
import { changeLocale } from "@gaio/i18n/react";
import type { SupportedLocale } from "@gaio/i18n/core";
function handleLanguageChange(locale: SupportedLocale) {
changeLocale(locale); // Atualiza i18n + cookie
}
```
***
## Padrões de Tradução
[Seção intitulada “Padrões de Tradução”](#padrões-de-tradução)
### Convenção de Keys
[Seção intitulada “Convenção de Keys”](#convenção-de-keys)
**IMPORTANTE:** Todas as keys devem estar em **inglês** usando `snake_case`:
```typescript
// ✅ CORRETO - keys em inglês, descritivas
t("validation:required");
t("validation:invalid_email");
t("common:actions.save");
t("common:messages.success.saved");
// ❌ ERRADO - keys em português
t("validation:campo_obrigatorio");
t("validation:email_invalido");
t("common:acoes.salvar");
```
### Texto Simples
[Seção intitulada “Texto Simples”](#texto-simples)
```tsx
import { useT } from "@gaio/i18n/react";
function SaveButton() {
const { t } = useT();
return ;
}
```
locales/pt-BR/common.json
```json
{
"actions": {
"save": "Salvar",
"cancel": "Cancelar",
"confirm": "Confirmar"
}
}
```
### Com Interpolação
[Seção intitulada “Com Interpolação”](#com-interpolação)
```tsx
const { t } = useT();
// Simples
t("welcome", { name: "João" }); // "Olá, João!"
// Múltiplas variáveis
t("summary", { count: 5, total: 100 }); // "5 de 100 itens"
```
```json
{
"welcome": "Olá, {{name}}!",
"summary": "{{count}} de {{total}} itens"
}
```
### JSX Complexo (Trans)
[Seção intitulada “JSX Complexo (Trans)”](#jsx-complexo-trans)
Use o componente `Trans` quando precisar de JSX dentro da tradução:
```tsx
import { Trans } from "@gaio/i18n/react";
Ao continuar, você aceita os Termos de Uso
;
```
```json
{
"terms": "Ao continuar, você aceita os <1>Termos de Uso"
}
```
### Toast Notifications
[Seção intitulada “Toast Notifications”](#toast-notifications)
```tsx
import { useT } from "@gaio/i18n/react";
import { toast } from "sonner";
function MyComponent() {
const { t } = useT();
const handleSave = async () => {
try {
await saveData();
toast.success(t("common:messages.success.saved"));
} catch {
toast.error(t("common:messages.error.save"));
}
};
}
```
### Fora de Componentes React
[Seção intitulada “Fora de Componentes React”](#fora-de-componentes-react)
Para usar traduções fora de componentes (utils, services), importe a instância `i18n` do módulo core:
```typescript
import { i18n } from "@gaio/i18n/core";
export function formatError(code: string): string {
return i18n.t(`errors:${code}`);
}
```
***
## Namespaces
[Seção intitulada “Namespaces”](#namespaces)
Os namespaces organizam traduções por domínio/feature:
| Namespace | Conteúdo | Uso |
| ------------ | ---------------------- | ------------------------------ |
| `common` | Botões, labels, status | UI compartilhada |
| `validation` | Mensagens de validação | Schemas Zod |
| `errors` | Erros HTTP/API | Error handlers |
| `auth` | Login, registro | `screens/auth/` |
| `inbox` | Chat, mensagens | `screens/dashboard/inbox/` |
| `workflows` | Editor de automação | `screens/dashboard/workflows/` |
| `settings` | Configurações | `screens/dashboard/settings/` |
### Vocabulário Padrão
[Seção intitulada “Vocabulário Padrão”](#vocabulário-padrão)
O namespace `common` contém elementos reutilizáveis em toda a aplicação. **Sempre use essas keys ao invés de criar duplicatas.**
#### Ações (Botões)
[Seção intitulada “Ações (Botões)”](#ações-botões)
common.json
```json
{
"actions": {
"save": "Salvar",
"cancel": "Cancelar",
"confirm": "Confirmar",
"create": "Criar",
"edit": "Editar",
"delete": "Excluir",
"remove": "Remover",
"add": "Adicionar",
"send": "Enviar",
"back": "Voltar",
"next": "Próximo",
"previous": "Anterior",
"close": "Fechar",
"open": "Abrir",
"search": "Buscar",
"filter": "Filtrar",
"clear": "Limpar",
"copy": "Copiar",
"paste": "Colar",
"duplicate": "Duplicar",
"refresh": "Atualizar",
"load_more": "Carregar mais",
"view_more": "Ver mais",
"view_less": "Ver menos",
"expand": "Expandir",
"collapse": "Recolher",
"export": "Exportar",
"import": "Importar",
"download": "Baixar",
"upload": "Enviar arquivo"
}
}
```
**Uso:**
```tsx
t("common:actions.save"); // "Salvar"
t("common:actions.cancel"); // "Cancelar"
```
#### Status
[Seção intitulada “Status”](#status)
common.json
```json
{
"status": {
"active": "Ativo",
"inactive": "Inativo",
"pending": "Pendente",
"approved": "Aprovado",
"rejected": "Rejeitado",
"completed": "Concluído",
"in_progress": "Em andamento",
"paused": "Pausado",
"canceled": "Cancelado",
"archived": "Arquivado",
"draft": "Rascunho",
"published": "Publicado",
"scheduled": "Agendado",
"expired": "Expirado",
"error": "Erro",
"success": "Sucesso",
"loading": "Carregando...",
"processing": "Processando..."
}
}
```
**Uso:**
```tsx
t("common:status.active"); // "Ativo"
t("common:status.pending"); // "Pendente"
```
#### Labels de Campos
[Seção intitulada “Labels de Campos”](#labels-de-campos)
common.json
```json
{
"fields": {
"name": "Nome",
"email": "E-mail",
"phone": "Telefone",
"password": "Senha",
"confirm_password": "Confirmar senha",
"description": "Descrição",
"title": "Título",
"date": "Data",
"time": "Hora",
"start_date": "Data de início",
"end_date": "Data de término",
"address": "Endereço",
"city": "Cidade",
"state": "Estado",
"country": "País",
"zip_code": "CEP",
"cpf": "CPF",
"cnpj": "CNPJ",
"notes": "Observação",
"attachment": "Anexo",
"file": "Arquivo",
"image": "Imagem",
"link": "Link",
"url": "URL",
"quantity": "Quantidade",
"value": "Valor",
"price": "Preço",
"total": "Total"
}
}
```
**Uso:**
```tsx
t("common:fields.name"); // "Nome"
t("common:fields.email"); // "E-mail"
```
#### Placeholders
[Seção intitulada “Placeholders”](#placeholders)
common.json
```json
{
"placeholders": {
"search": "Buscar...",
"select": "Selecione...",
"type": "Digite...",
"email": "exemplo@email.com",
"phone": "(00) 00000-0000",
"date": "DD/MM/AAAA"
}
}
```
**Uso:**
```tsx
```
#### Mensagens Genéricas
[Seção intitulada “Mensagens Genéricas”](#mensagens-genéricas)
common.json
```json
{
"messages": {
"success": {
"saved": "Salvo com sucesso",
"created": "Criado com sucesso",
"updated": "Atualizado com sucesso",
"deleted": "Excluído com sucesso",
"sent": "Enviado com sucesso",
"copied": "Copiado para a área de transferência"
},
"error": {
"generic": "Ocorreu um erro. Tente novamente.",
"connection": "Erro de conexão. Verifique sua internet.",
"load": "Erro ao carregar dados",
"save": "Erro ao salvar",
"delete": "Erro ao excluir",
"permission": "Você não tem permissão para esta ação"
},
"confirmation": {
"delete": "Tem certeza que deseja excluir?",
"cancel": "Tem certeza que deseja cancelar?",
"exit": "Tem certeza que deseja sair?",
"discard": "Descartar alterações não salvas?"
},
"empty": {
"list": "Nenhum item encontrado",
"search": "Nenhum resultado para sua busca",
"data": "Sem dados para exibir"
}
}
}
```
**Uso:**
```tsx
toast.success(t("common:messages.success.saved"));
toast.error(t("common:messages.error.generic"));
```
#### Tempo e Datas
[Seção intitulada “Tempo e Datas”](#tempo-e-datas)
common.json
```json
{
"time": {
"today": "Hoje",
"yesterday": "Ontem",
"tomorrow": "Amanhã",
"now": "Agora",
"just_now": "Há pouco",
"seconds": "{{count}} segundo",
"seconds_plural": "{{count}} segundos",
"minutes": "{{count}} minuto",
"minutes_plural": "{{count}} minutos",
"hours": "{{count}} hora",
"hours_plural": "{{count}} horas",
"days": "{{count}} dia",
"days_plural": "{{count}} dias",
"weeks": "{{count}} semana",
"weeks_plural": "{{count}} semanas",
"months": "{{count}} mês",
"months_plural": "{{count}} meses"
}
}
```
**Uso:**
```tsx
t("common:time.days", { count: 5 }); // "5 dias"
t("common:time.today"); // "Hoje"
```
#### Paginação e Listas
[Seção intitulada “Paginação e Listas”](#paginação-e-listas)
common.json
```json
{
"pagination": {
"page": "Página {{current}} de {{total}}",
"items": "{{count}} item",
"items_plural": "{{count}} itens",
"showing": "Mostrando {{from}} a {{to}} de {{total}}",
"per_page": "Por página",
"first": "Primeira",
"last": "Última"
}
}
```
#### Regra de Ouro
[Seção intitulada “Regra de Ouro”](#regra-de-ouro)
```tsx
// ❌ ERRADO - Criar key específica para algo comum
t("workflows:save");
t("inbox:cancel_button");
t("settings:delete_account");
// ✅ CORRETO - Usar vocabulary padrão
t("common:actions.save");
t("common:actions.cancel");
t("common:actions.delete");
// ✅ CORRETO - Key específica apenas para contexto único
t("settings:account.delete_permanently"); // Ação específica com consequência diferente
```
### Criar Novo Namespace
[Seção intitulada “Criar Novo Namespace”](#criar-novo-namespace)
Guia passo a passo para adicionar um novo escopo de tradução.
#### Criar Arquivos JSON
[Seção intitulada “Criar Arquivos JSON”](#criar-arquivos-json)
```bash
# Estrutura de arquivos
packages/i18n/src/locales/
├── pt-BR/
│ └── campaigns.json # NOVO
└── en/
└── campaigns.json # NOVO
```
packages/i18n/src/locales/pt-BR/campaigns.json
```json
{
"title": "Campanhas",
"create": "Criar campanha",
"edit": "Editar campanha",
"delete": "Excluir campanha",
"status": {
"active": "Ativa",
"paused": "Pausada",
"finished": "Finalizada"
},
"messages": {
"created_success": "Campanha criada com sucesso",
"updated_success": "Campanha atualizada com sucesso",
"deleted_success": "Campanha excluída com sucesso",
"error_create": "Erro ao criar campanha"
}
}
```
packages/i18n/src/locales/en/campaigns.json
```json
{
"title": "Campaigns",
"create": "Create campaign",
"edit": "Edit campaign",
"delete": "Delete campaign",
"status": {
"active": "Active",
"paused": "Paused",
"finished": "Finished"
},
"messages": {
"created_success": "Campaign created successfully",
"updated_success": "Campaign updated successfully",
"deleted_success": "Campaign deleted successfully",
"error_create": "Error creating campaign"
}
}
```
#### Registrar no Index de Locales
[Seção intitulada “Registrar no Index de Locales”](#registrar-no-index-de-locales)
packages/i18n/src/locales/pt-BR/index.ts
```typescript
import auth from "./auth.json";
import campaigns from "./campaigns.json";
import common from "./common.json";
import errors from "./errors.json";
import inbox from "./inbox.json";
import settings from "./settings.json";
import validation from "./validation.json";
import workflows from "./workflows.json";
export default {
auth,
campaigns,
common,
errors,
inbox,
settings,
validation,
workflows,
};
```
#### Adicionar nas Constantes
[Seção intitulada “Adicionar nas Constantes”](#adicionar-nas-constantes)
packages/i18n/src/core/constants.ts
```typescript
export const NAMESPACES = [
"auth",
"campaigns",
"common",
"errors",
"inbox",
"settings",
"validation",
"workflows",
] as const;
```
#### Atualizar Tipagem TypeScript
[Seção intitulada “Atualizar Tipagem TypeScript”](#atualizar-tipagem-typescript)
packages/i18n/src/types/resources.d.ts
```typescript
import "i18next";
import auth from "../locales/pt-BR/auth.json";
import campaigns from "../locales/pt-BR/campaigns.json";
import common from "../locales/pt-BR/common.json";
import errors from "../locales/pt-BR/errors.json";
import inbox from "../locales/pt-BR/inbox.json";
import settings from "../locales/pt-BR/settings.json";
import validation from "../locales/pt-BR/validation.json";
import workflows from "../locales/pt-BR/workflows.json";
declare module "i18next" {
interface CustomTypeOptions {
defaultNS: "common";
resources: {
auth: typeof auth;
campaigns: typeof campaigns;
common: typeof common;
errors: typeof errors;
inbox: typeof inbox;
settings: typeof settings;
validation: typeof validation;
workflows: typeof workflows;
};
}
}
```
#### Usar o Novo Namespace
[Seção intitulada “Usar o Novo Namespace”](#usar-o-novo-namespace)
packages/console/src/screens/dashboard/campaigns/index.tsx
```tsx
import { useT } from "@gaio/i18n/react";
function CampaignsPage() {
const { t } = useT("campaigns");
return (
{t("title")}
);
}
```
```tsx
// Acesso a keys aninhadas
t("campaigns:status.active"); // "Ativa"
t("campaigns:messages.created_success"); // "Campanha criada com sucesso"
```
#### Checklist Novo Namespace
[Seção intitulada “Checklist Novo Namespace”](#checklist-novo-namespace)
* [ ] Criar `pt-BR/{namespace}.json`
* [ ] Criar `en/{namespace}.json`
* [ ] Adicionar import em `locales/pt-BR/index.ts`
* [ ] Adicionar import em `locales/en/index.ts`
* [ ] Adicionar em `NAMESPACES` em `constants.ts`
* [ ] Adicionar em `resources.d.ts` para intellisense
* [ ] Testar com `useT('namespace')` no componente
***
## Integração com Zod
[Seção intitulada “Integração com Zod”](#integração-com-zod)
O `zodMessages` fornece mensagens de validação traduzidas para schemas Zod.
### Mensagens Disponíveis
[Seção intitulada “Mensagens Disponíveis”](#mensagens-disponíveis)
| Função | Exemplo de Uso | Key |
| --------------------- | --------------------------------------- | -------------------------------- |
| `required()` | `.min(1, zodMessages.required())` | `validation:required` |
| `minLength(n)` | `.min(3, zodMessages.minLength(3))` | `validation:min_length` |
| `maxLength(n)` | `.max(100, zodMessages.maxLength(100))` | `validation:max_length` |
| `invalidEmail()` | `.email(zodMessages.invalidEmail())` | `validation:invalid_email` |
| `invalidUrl()` | `.url(zodMessages.invalidUrl())` | `validation:invalid_url` |
| `invalidPhone()` | Custom validator | `validation:invalid_phone` |
| `passwordMismatch()` | Refine de confirmação | `validation:password_mismatch` |
| `passwordMinLength()` | `.min(8, ...)` | `validation:password_min_length` |
| `passwordUppercase()` | Regex validator | `validation:password_uppercase` |
| `passwordLowercase()` | Regex validator | `validation:password_lowercase` |
| `passwordNumber()` | Regex validator | `validation:password_number` |
| `passwordSpecial()` | Regex validator | `validation:password_special` |
### Exemplo de Schema
[Seção intitulada “Exemplo de Schema”](#exemplo-de-schema)
```typescript
import { z } from "zod";
import { zodMessages } from "@gaio/i18n/core";
export const RegisterSchema = z
.object({
name: z
.string()
.min(1, zodMessages.required())
.max(100, zodMessages.maxLength(100)),
email: z
.string()
.min(1, zodMessages.required())
.email(zodMessages.invalidEmail()),
password: z
.string()
.min(8, zodMessages.passwordMinLength())
.regex(/[A-Z]/, zodMessages.passwordUppercase())
.regex(/[a-z]/, zodMessages.passwordLowercase())
.regex(/[0-9]/, zodMessages.passwordNumber()),
confirmPassword: z.string(),
})
.refine((data) => data.password === data.confirmPassword, {
message: zodMessages.passwordMismatch(),
path: ["confirmPassword"],
});
```
### Mensagens Customizadas
[Seção intitulada “Mensagens Customizadas”](#mensagens-customizadas)
Para mensagens específicas de um form, use `i18n.t()` diretamente:
```typescript
import { i18n, zodMessages } from "@gaio/i18n/core";
const WorkflowSchema = z.object({
name: z
.string()
.min(1, zodMessages.required())
.max(50, () => i18n.t("workflows:name_max_50")),
});
```
***
## Pluralização e Interpolação
[Seção intitulada “Pluralização e Interpolação”](#pluralização-e-interpolação)
### Pluralização
[Seção intitulada “Pluralização”](#pluralização)
i18next usa sufixos para pluralização:
locales/pt-BR/common.json
```json
{
"message": "{{count}} mensagem",
"message_plural": "{{count}} mensagens",
"message_zero": "Nenhuma mensagem"
}
```
```typescript
t("message", { count: 0 }); // "Nenhuma mensagem"
t("message", { count: 1 }); // "1 mensagem"
t("message", { count: 5 }); // "5 mensagens"
```
### Regras de Sufixos
[Seção intitulada “Regras de Sufixos”](#regras-de-sufixos)
| Sufixo | Quando usado |
| --------- | ---------------------- |
| (nenhum) | count === 1 |
| `_plural` | count !== 1 |
| `_zero` | count === 0 (opcional) |
### Interpolação com Formatação
[Seção intitulada “Interpolação com Formatação”](#interpolação-com-formatação)
```json
{
"price": "R$ {{value, number}}",
"date": "{{date, datetime}}"
}
```
```typescript
t("price", { value: 1234.56 }); // "R$ 1.234,56" (formatado pelo locale)
```
### Context (Gênero)
[Seção intitulada “Context (Gênero)”](#context-gênero)
```json
{
"user_updated": "Usuário atualizado",
"user_updated_male": "Usuário atualizado",
"user_updated_female": "Usuária atualizada"
}
```
```typescript
t("user_updated", { context: "female" }); // "Usuária atualizada"
```
***
## Melhores Práticas de Interpolação
[Seção intitulada “Melhores Práticas de Interpolação”](#melhores-práticas-de-interpolação)
### Quando Usar Interpolação
[Seção intitulada “Quando Usar Interpolação”](#quando-usar-interpolação)
Use interpolação **apenas** para valores dinâmicos que só podem ser conhecidos em runtime:
```typescript
// ✅ CORRETO - valor dinâmico (nome do usuário vem do banco)
t("welcome", { name: user.name });
// ✅ CORRETO - valores numéricos dinâmicos
t("items_count", { count: items.length });
// ✅ CORRETO - timestamps e datas
t("last_updated", { date: formatDate(updatedAt) });
```
### Quando NÃO Usar Interpolação
[Seção intitulada “Quando NÃO Usar Interpolação”](#quando-não-usar-interpolação)
Evite interpolação para valores conhecidos no momento da tradução. Use chaves separadas:
```typescript
// ❌ ERRADO - concatenação de strings
t("error_prefix") + errorType + t("error_suffix");
// ❌ ERRADO - interpolação para valores conhecidos
t("file_type_error", { type: "PDF" });
// ✅ CORRETO - chaves separadas e autocontidas
t("errors.invalid_pdf_file");
t("errors.invalid_image_file");
t("errors.invalid_document_file");
```
### Tabela de Decisão
[Seção intitulada “Tabela de Decisão”](#tabela-de-decisão)
| Cenário | Abordagem | Exemplo |
| ----------------------------- | --------------------------- | -------------------------------------------- |
| Nome de usuário | Interpolação | `Olá, {{name}}` |
| Contagens | Interpolação + Pluralização | `{{count}} mensagem` / `{{count}} mensagens` |
| Tipos de arquivo conhecidos | Chaves separadas | `invalid_pdf_file`, `invalid_image_file` |
| Status conhecidos | Chaves separadas | `status.active`, `status.inactive` |
| Mensagens de erro específicas | Chaves separadas | `errors.network_error`, `errors.auth_error` |
| Métodos de pagamento | Chaves separadas | `payment.credit_card`, `payment.paypal` |
***
## Formatação HTML em Traduções
[Seção intitulada “Formatação HTML em Traduções”](#formatação-html-em-traduções)
Quando traduções precisam conter formatação (negrito, itálico, links), use o componente `Trans` do `react-i18next` em vez de `dangerouslySetInnerHTML`.
### defaultTransComponents
[Seção intitulada “defaultTransComponents”](#defaulttranscomponents)
Use o helper `defaultTransComponents` para elementos HTML padrão:
```typescript
import { defaultTransComponents } from "@gaio/i18n/react";
// Elementos suportados:
// e →
// e →
//
→
// →
```
### Exemplo Completo
[Seção intitulada “Exemplo Completo”](#exemplo-completo)
```tsx
import { Trans, defaultTransComponents } from "@gaio/i18n/react";
export const InviteDialog = () => {
return (
);
};
```
### Quando Usar `Trans` vs `t()`
[Seção intitulada “Quando Usar Trans vs t()”](#quando-usar-trans-vs-t)
| Cenário | Use | Exemplo |
| -------------------------------------- | ------------------------------- | ------------------------------------------------------------- |
| Texto simples sem formatação | `t()` | `t('common:labels.save')` |
| Texto com interpolação simples | `t()` | `t('messages.hello', { name })` |
| Texto com **negrito**, *itálico*, etc. | `Trans` | `` |
| Texto com links | `Trans` + `createLinkComponent` | Ver exemplo acima |
***
## Seletor de Idioma
[Seção intitulada “Seletor de Idioma”](#seletor-de-idioma)
### Componente de Seleção
[Seção intitulada “Componente de Seleção”](#componente-de-seleção)
```tsx
import { useT, useLocale, changeLocale } from "@gaio/i18n/react";
import { LOCALE_LABELS, SUPPORTED_LOCALES } from "@gaio/i18n/core";
export function LanguageSelector() {
const { t } = useT();
const currentLocale = useLocale();
return (
);
}
```
### Persistência
[Seção intitulada “Persistência”](#persistência)
A preferência de idioma é salva automaticamente em um cookie `ga:i18n` (duração: 1 ano).
Ordem de detecção:
1. `cookie` (preferência salva)
2. `navigator.language` (idioma do navegador)
3. `pt-BR` (fallback)
***
## CLI e Extração
[Seção intitulada “CLI e Extração”](#cli-e-extração)
### Comandos
[Seção intitulada “Comandos”](#comandos)
```bash
# Extrair strings do código para os JSONs
npm run i18n:extract -w @gaio/i18n
# Verificar se há strings não extraídas (CI)
npm run i18n:check -w @gaio/i18n
```
### Workflow de Tradução
[Seção intitulada “Workflow de Tradução”](#workflow-de-tradução)
1. Desenvolver feature com strings usando `t('key')`
2. Rodar `npm run i18n:extract -w @gaio/i18n`
3. Preencher traduções em `pt-BR/*.json`
***
## Validação i18n (CI/CD)
[Seção intitulada “Validação i18n (CI/CD)”](#validação-i18n-cicd)
### Comandos da CLI Gaio
[Seção intitulada “Comandos da CLI Gaio”](#comandos-da-cli-gaio)
```bash
gaio i18n validate # Validação completa (usado no CI)
gaio i18n validate --fix # Validação com auto-fix de chaves órfãs
gaio i18n extract # Extrair chaves de tradução do código
gaio i18n status # Ver status das traduções (completude)
gaio i18n lint # Detectar hardcoded strings
```
### O que é Validado
[Seção intitulada “O que é Validado”](#o-que-é-validado)
1. **Chaves Órfãs** - Chaves que existem nos JSONs mas não são usadas no código
2. **Hardcoded Strings** - Strings visíveis ao usuário que não usam `t()`
3. **Status das Traduções** - Chaves faltantes entre idiomas
### Workflow de Desenvolvimento
[Seção intitulada “Workflow de Desenvolvimento”](#workflow-de-desenvolvimento)
1. `gaio i18n extract` - Extrair novas chaves
2. Preencher traduções em ambos idiomas
3. `gaio i18n validate` - Validar localmente
4. Corrigir problemas com `--fix` se necessário
***
## Testes
[Seção intitulada “Testes”](#testes)
### Test Provider
[Seção intitulada “Test Provider”](#test-provider)
```tsx
import { I18nProvider } from "@gaio/i18n/react";
export function TestI18nWrapper({ children }: { children: ReactNode }) {
return {children};
}
render(
,
);
```
### Mock de Traduções
[Seção intitulada “Mock de Traduções”](#mock-de-traduções)
```typescript
vi.mock("@gaio/i18n/react", () => ({
useT: () => ({
t: (key: string) => key,
}),
}));
```
***
## Anti-patterns
[Seção intitulada “Anti-patterns”](#anti-patterns)
```tsx
// ❌ ERRADO - Strings hardcoded
;
// ✅ CORRETO
const { t } = useT();
;
```
```tsx
// ❌ ERRADO - Concatenação de strings
t("you_have") + count + t("messages");
// ✅ CORRETO - Interpolação
t("you_have_messages", { count });
```
```tsx
// ❌ ERRADO - Keys em português
t("validation:campo_obrigatorio");
// ✅ CORRETO
t("validation:required");
```
```tsx
// ❌ ERRADO - useT em loops
{
items.map((item) => {
const { t } = useT(); // Hook em cada iteração!
return {t("item")};
});
}
// ✅ CORRETO
const { t } = useT();
{
items.map((item) => {t("item")});
}
```
***
## TypeScript
[Seção intitulada “TypeScript”](#typescript)
Para ter intellisense das variáveis de interpolação em cada tradução, configure os tipos:
packages/i18n/src/types/resources.d.ts
```typescript
import "i18next";
import common from "../locales/pt-BR/common.json";
// ... outros imports
declare module "i18next" {
interface CustomTypeOptions {
defaultNS: "common";
resources: {
common: typeof common;
// ... outros namespaces
};
}
}
```
### Benefícios
[Seção intitulada “Benefícios”](#benefícios)
```typescript
// ✅ Autocomplete de keys
t("welcome"); // Sugere todas as keys disponíveis
// ✅ Erro se key não existe
t("key_inexistente"); // TypeScript error!
// ✅ Autocomplete de variáveis de interpolação
t("welcome", { name: "João" }); // TypeScript sabe que 'name' é obrigatório
```
***
## Referências
[Seção intitulada “Referências”](#referências)
* **i18next:**
* **react-i18next:**
* **TypeScript setup:**
# Visão Geral
> Arquitetura e conceitos do frontend GAIO
Documentação do frontend do ecossistema GAIO.
## Índice
[Seção intitulada “Índice”](#índice)
* [Stack Técnica](/frontend/general/) — Tecnologias, padrões e convenções do projeto
* [Gaio CLI](/cli/overview/) — Comandos e ferramentas da CLI
* [Internacionalização (i18n)](/frontend/i18n/) — Guia completo de i18n com i18next
* [Formulários](/frontend/forms/) — Padrões com React Hook Form + Zod
* [Token Refresh](/frontend/auth-refresh/) — Coordenação de refresh com single-flight pattern
### Testing
[Seção intitulada “Testing”](#testing)
* [Arquitetura de Testes](/frontend/testing/overview/) — Estrutura e organização dos testes
* [Shared Utilities](/frontend/testing/utils/shared/) — Utilitários compartilhados entre testes
* [Utils](/frontend/testing/utils/overview/) — Vitest e MSW helpers
* [E2E](/frontend/testing/e2e/) — Testes end-to-end com Playwright
* [API Mocks](/frontend/testing/api-mocks/) — Padrões de mock para E2E
### Templates
[Seção intitulada “Templates”](#templates)
* [Fluxos](/frontend/templates/flows/) — Fluxos do funil de templates
* [KPIs](/frontend/templates/kpis-funnel/) — Métricas e KPIs do funil
* [Tracking](/frontend/templates/tracking/) — Eventos e analytics com PostHog
# Fluxos
> Fluxos de usuário e jornadas
Este documento descreve o fluxo de instalação de templates. O objetivo é suportar instalação com ou sem plano/cupom, usando o caminho: **Auth → Profile → Checkout → Success**.
## Etapas do Funil
[Seção intitulada “Etapas do Funil”](#etapas-do-funil)
| Step | Descrição | Rota |
| ------------------ | ------------------------------------------- | ------------------------------------- |
| `template_view` | Visualização do template | `/t/{slug}` |
| `auth_pending` | Autenticação | `/t/{slug}/install/` |
| `profile_pending` | Completar perfil + aceitar compartilhamento | `/t/{slug}/install/profile` |
| `checkout_pending` | Checkout | `/t/{slug}/install/checkout` |
| `success` | Sucesso | `/t/{subscriptionId}/install/success` |
## Transições principais
[Seção intitulada “Transições principais”](#transições-principais)
| Estado Atual | Evento | Próximo Estado | Observação |
| ------------------ | ----------------- | ------------------ | ----------------------------- |
| `template_view` | `install_click` | `auth_pending` | Início do funil |
| `auth_pending` | `auth_success` | `profile_pending` | Usuário sem perfil completo |
| `auth_pending` | `auth_success` | `checkout_pending` | Usuário com perfil completo |
| `auth_pending` | `auth_error` | `auth_pending` | Exibe erro e permite retry |
| `profile_pending` | `profile_submit` | `checkout_pending` | Dados válidos + consentimento |
| `checkout_pending` | `payment_success` | `success` | Assinatura criada |
| `checkout_pending` | `payment_error` | `checkout_pending` | Exibe erro e permite retry |
## Regras de navegação
[Seção intitulada “Regras de navegação”](#regras-de-navegação)
* Se o usuário já estiver autenticado e com perfil completo, pode ir direto para `checkout_pending`.
* Se não houver plano/cupom, o checkout pode ser apresentado como **R$ 0** ou com plano nulo (de acordo com o backend).
* O `subscriptionId` é usado apenas na rota de sucesso.
* O consentimento de compartilhamento é obrigatório para avançar do perfil para o checkout.
## Estado mínimo do funil
[Seção intitulada “Estado mínimo do funil”](#estado-mínimo-do-funil)
```ts
interface InstallationState {
sessionId: string | null;
currentStep:
| "template_view"
| "auth_pending"
| "profile_pending"
| "checkout_pending"
| "success";
completedSteps: Array<
| "template_view"
| "auth_pending"
| "profile_pending"
| "checkout_pending"
| "success"
>;
templateId?: string;
templateSlug?: string;
planId?: string | null;
couponId?: string | null;
consent?: boolean;
}
```
## Eventos de tracking
[Seção intitulada “Eventos de tracking”](#eventos-de-tracking)
Os eventos estão em [Tracking](/frontend/templates/tracking). Eventos adicionais podem ser criados para insights mais detalhados, mas não devem ser usados para controle de fluxo.
# KPIs
> Métricas e conversão
Este documento descreve os KPIs mínimos para o funil de templates, alinhados ao tracking.
## Etapas
[Seção intitulada “Etapas”](#etapas)
### Template
[Seção intitulada “Template”](#template)
* **Install Clicks** = `COUNT(template_install_click)`
### Auth
[Seção intitulada “Auth”](#auth)
* **Auth Starts** = `COUNT(auth_register_start) + COUNT(auth_login_start) + COUNT(auth_instagram_start)`
* **Auth Completions** = `COUNT(auth_register_success) + COUNT(auth_login_success) + COUNT(auth_instagram_success)`
* **Auth Errors** = `COUNT(auth_register_failure) + COUNT(auth_login_failure) + COUNT(auth_instagram_failure)`
* **Auth Success Rate** = `auth_completions / auth_starts`
### Profile (via Pageviews)
[Seção intitulada “Profile (via Pageviews)”](#profile-via-pageviews)
* **Profile Views** = `COUNT($pageview WHERE $current_url CONTAINS '/install/profile')`
* **Profile Completed** = `COUNT(profile_completed)`
* **Drop-off Auth → Profile** = `1 - (profile_views / auth_completions)`
### Checkout
[Seção intitulada “Checkout”](#checkout)
* **Checkout Views** = `COUNT(checkout_viewed)`
* **Checkout Submissions** = `COUNT(checkout_submitted)`
* **Checkout Completions** = `COUNT(checkout_completed)`
* **Checkout Error Rate** = `checkout_errors / checkout_submitted`
* **Checkout Conversion Rate** = `checkout_completions / checkout_views`
### Funil completo
[Seção intitulada “Funil completo”](#funil-completo)
* **Total Funnel Conversion** = `template_signup_complete / template_install_click`
* **Churn por Etapa** = Usar funil de pageviews (Auth → Profile → Consent → Checkout → Success)
## Dashboard PostHog
[Seção intitulada “Dashboard PostHog”](#dashboard-posthog)
O dashboard **Funil de Templates** contém todos os insights necessários:
### Insights de Checkout
[Seção intitulada “Insights de Checkout”](#insights-de-checkout)
* **Funil de Checkout Detalhado** - checkout\_viewed → submitted → completed
* **Erros vs Submissões** - Taxa de erro ao longo do tempo
* **Tipos de Erro** - Breakdown por error\_message
* **Views vs Conclusões** - Gap de conversão no checkout
### Insights de Pageviews
[Seção intitulada “Insights de Pageviews”](#insights-de-pageviews)
* **Funil Completo por Páginas** - Conversão entre todas as etapas
* **Pageviews por Etapa** - Volume de cada etapa ao longo do tempo
### Insights de Auth
[Seção intitulada “Insights de Auth”](#insights-de-auth)
* **Distribuição de Métodos** - Register vs Login vs Instagram
* **Funil de Register** - auth\_register\_start → success
* **Funil de Login** - auth\_login\_start → success
## Segmentações recomendadas
[Seção intitulada “Segmentações recomendadas”](#segmentações-recomendadas)
* `plan_id` (com plano vs sem plano)
* `coupon_id` (com cupom vs sem cupom)
* `is_zero_cost` (cupom 100% de desconto)
* `auth_method` (registration, login, instagram)
* `error_message` (tipos de erro no checkout)
## Eventos usados
[Seção intitulada “Eventos usados”](#eventos-usados)
Todos os eventos estão definidos em [Tracking](/frontend/templates/tracking).
**Eventos principais**:
* `template_install_click`, `template_signup_complete`
* Auth: `auth_{method}_{outcome}` (register/login/instagram + start/success/failure)
* Profile: `profile_completed`, `consent_accepted`
* Checkout: `checkout_viewed`, `checkout_submitted`, `checkout_completed`, `checkout_error`
* Pageviews: `$pageview` com filtros de URL para cada etapa do funil
# Tracking
> Eventos e monitoramento
O objetivo é medir toda a jornada do usuário ao ativar um template **com ou sem plano/cupom**, sem eventos desnecessários.
## Escopo
[Seção intitulada “Escopo”](#escopo)
Eventos **implementados**:
* `template_install_click` - Clique no botão instalar
* `template_signup_complete` - Conclusão com sucesso
* **Auth Registration**: `auth_register_start`, `auth_register_success`, `auth_register_failure`
* **Auth Login**: `auth_login_start`, `auth_login_success`, `auth_login_failure`
* **Auth Instagram**: `auth_instagram_start`, `auth_instagram_success`, `auth_instagram_failure`
* **Profile**: `profile_completed` - Conclusão do perfil
* **Consent**: `consent_accepted` - Aceitação de compartilhamento
* **Checkout**: `checkout_viewed`, `checkout_submitted`, `checkout_completed`, `checkout_error`
## Propriedades comuns
[Seção intitulada “Propriedades comuns”](#propriedades-comuns)
Todos os eventos incluem, quando disponíveis:
* `template_id` - ID único do template
* `template_slug` - Slug amigável do template
* `plan_id` - ID do plano (se aplicável)
* `amount_in_cents` - Valor do plano em centavos
* `coupon_id` - ID do cupom (se aplicável)
* `percent_off` - Percentual de desconto do cupom
* `duration_in_months` - Duração do desconto em meses
* `applies_first_month_only` - Se o desconto aplica apenas ao primeiro mês
**Nota**: O `funnel_session_id` (PostHog session) é gerenciado automaticamente pelo SDK
## Eventos e payloads
[Seção intitulada “Eventos e payloads”](#eventos-e-payloads)
### Eventos do Funil Principal
[Seção intitulada “Eventos do Funil Principal”](#eventos-do-funil-principal)
#### `template_install_click`
[Seção intitulada “template\_install\_click”](#template_install_click)
Disparado quando o usuário clica no botão instalar.
```ts
interface TemplateInstallClickEvent {
template_id: string;
template_slug: string;
plan_id?: string;
coupon_id?: string;
amount_in_cents?: number;
}
```
#### `template_form_start`
[Seção intitulada “template\_form\_start”](#template_form_start)
Disparado quando o usuário inicia o preenchimento do formulário de perfil.
```ts
interface TemplateFormStartEvent {
template_id: string;
template_slug: string;
plan_id?: string;
coupon_id?: string;
}
```
#### `template_form_drop`
[Seção intitulada “template\_form\_drop”](#template_form_drop)
Disparado quando o usuário abandona o funil (inatividade ou navegação para fora).
```ts
interface TemplateFormDropEvent {
template_id: string;
template_slug: string;
plan_id?: string;
coupon_id?: string;
abandonment_point: 'account' | 'contact' | 'wizard_profile' | 'wizard_discovery' | 'activation';
}
```
#### `template_signup_complete`
[Seção intitulada “template\_signup\_complete”](#template_signup_complete)
Disparado quando o usuário chega na página de sucesso após ativação.
```ts
interface TemplateSignupCompleteEvent {
template_id: string;
template_slug: string;
plan_id?: string;
coupon_id?: string;
amount_in_cents?: number;
}
```
***
### Eventos de Autenticação
[Seção intitulada “Eventos de Autenticação”](#eventos-de-autenticação)
Todos os eventos de auth seguem o padrão: `auth_{method}_{outcome}` onde:
* **method**: `register`, `login`, `instagram`
* **outcome**: `start`, `success`, `failure`
#### `auth_register_start` / `auth_register_success` / `auth_register_failure`
[Seção intitulada “auth\_register\_start / auth\_register\_success / auth\_register\_failure”](#auth_register_start--auth_register_success--auth_register_failure)
```ts
interface AuthRegisterEvent {
auth_method: 'registration';
template_id?: string;
template_slug?: string;
error_code?: string; // apenas em failure
error_message?: string; // apenas em failure
}
```
#### `auth_login_start` / `auth_login_success` / `auth_login_failure`
[Seção intitulada “auth\_login\_start / auth\_login\_success / auth\_login\_failure”](#auth_login_start--auth_login_success--auth_login_failure)
```ts
interface AuthLoginEvent {
auth_method: 'login';
template_id?: string;
template_slug?: string;
error_code?: string; // apenas em failure
error_message?: string; // apenas em failure
}
```
#### `auth_instagram_start` / `auth_instagram_success` / `auth_instagram_failure`
[Seção intitulada “auth\_instagram\_start / auth\_instagram\_success / auth\_instagram\_failure”](#auth_instagram_start--auth_instagram_success--auth_instagram_failure)
```ts
interface AuthInstagramEvent {
auth_method: 'instagram';
template_id?: string;
template_slug?: string;
error_code?: string; // apenas em failure
error_message?: string; // apenas em failure
}
```
***
### Eventos de Community Modal
[Seção intitulada “Eventos de Community Modal”](#eventos-de-community-modal)
#### `community_modal_view`
[Seção intitulada “community\_modal\_view”](#community_modal_view)
Disparado quando o modal de preview é aberto ou fechado.
```ts
interface CommunityModalViewEvent {
template_id: string;
template_slug: string;
modal_state: 'open' | 'close';
}
```
#### `community_modal_install_click`
[Seção intitulada “community\_modal\_install\_click”](#community_modal_install_click)
Disparado quando o usuário clica em instalar dentro do modal da comunidade.
```ts
interface CommunityModalInstallClickEvent {
template_id: string;
template_slug: string;
plan_id?: string;
coupon_id?: string;
}
```
## Tracking por Pageviews
[Seção intitulada “Tracking por Pageviews”](#tracking-por-pageviews)
Para medir churn entre etapas do funil, use **pageviews automáticos** do PostHog ao invés de eventos customizados:
### URLs do Funil
[Seção intitulada “URLs do Funil”](#urls-do-funil)
* **Auth**: `/t/{slug}/install` - Página de autenticação
* **Profile**: `/t/{slug}/install/profile` - Página de perfil
* **Consent**: `/t/{slug}/install/consent` - Página de consentimento
* **Checkout**: `/t/{slug}/install/checkout` - Página de checkout
* **Success**: `/t/{slug}/install/success` - Página de sucesso
### Insights Baseados em Pageviews
[Seção intitulada “Insights Baseados em Pageviews”](#insights-baseados-em-pageviews)
1. **Funil Completo por Páginas** - Mede conversão Auth → Profile → Consent → Checkout → Success
2. **Pageviews por Etapa - Tendência** - Compara volume de cada etapa ao longo do tempo
3. **Churn entre Etapas** - Diferença entre pageviews consecutivas identifica abandono
**Vantagens**:
* Sem código adicional (autocapture do PostHog)
* Tempo médio entre etapas calculado automaticamente
* Sessões rastreadas automaticamente
* Menos eventos customizados = menos manutenção
# API Mocks
> Helpers para mockar APIs em testes E2E
Helpers reutilizáveis para mockar APIs nos testes Playwright. **Use sempre esses helpers** em vez de criar mocks manualmente.
> **Ver também**: [Arquitetura de Testes](/frontend/testing/overview) | [Guia E2E](/frontend/testing/e2e)
## Objetivo
[Seção intitulada “Objetivo”](#objetivo)
* ✅ **Consistência**: Todos os testes usam os mesmos mocks
* ✅ **Manutenibilidade**: Mocks centralizados em um único lugar
* ✅ **Produtividade**: Setup rápido com funções pré-configuradas
* ✅ **Redução de código**: Menos boilerplate nos testes
## Uso Rápido
[Seção intitulada “Uso Rápido”](#uso-rápido)
### Setup Completo (Fluxo de Template)
[Seção intitulada “Setup Completo (Fluxo de Template)”](#setup-completo-fluxo-de-template)
```typescript
import { setupTemplateFlowMocks } from "../helpers";
test.beforeEach(async ({ page }) => {
await setupTemplateFlowMocks(page, {
templateId: "template-123",
templateSlug: "test-template",
templateName: "My Template",
planId: null, // FREE ou 'plan-id' para PAID
});
});
```
### Setup Modular
[Seção intitulada “Setup Modular”](#setup-modular)
```typescript
import {
setupCommonApiMocks,
setupAuthMocks,
setupTemplateMocks,
} from "../helpers";
test.beforeEach(async ({ page }) => {
await setupCommonApiMocks(page);
await setupAuthMocks(page);
await setupTemplateMocks(page, { templateId: "my-template" });
});
```
## Helpers Disponíveis
[Seção intitulada “Helpers Disponíveis”](#helpers-disponíveis)
### `setupCommonApiMocks(page)`
[Seção intitulada “setupCommonApiMocks(page)”](#setupcommonapimockspage)
Mocks básicos necessários para páginas autenticadas:
* ✅ Current user
* ✅ Connections
* ✅ Subscription status
* ✅ Account info
* ✅ Catch-all para endpoints não mockados
**Quando usar**: Em praticamente todos os testes.
***
### `setupAuthMocks(page, options?)`
[Seção intitulada “setupAuthMocks(page, options?)”](#setupauthmockspage-options)
Mocks de autenticação:
* ✅ Login (`/api/console/login`)
* ✅ Sign-in (`/api/console/sign-in`)
* ✅ Sign-up (`/api/console/sign-up`)
* ✅ Email verification
**Opções**:
```typescript
{
invalidCredentials?: string[], // Emails com credenciais inválidas
existingEmails?: string[], // Emails já cadastrados
unverifiedEmails?: string[] // Emails não verificados
}
```
**Exemplo**:
```typescript
await setupAuthMocks(page, {
invalidCredentials: ["wrong@example.com"],
existingEmails: ["existing@example.com"],
});
```
***
### `setupProfileMocks(page)`
[Seção intitulada “setupProfileMocks(page)”](#setupprofilemockspage)
Mocks de atualização de perfil:
* ✅ Contact info (`/api/console/profile/contact-info`)
* ✅ Account metadata (`/api/console/account/metadata`)
* ✅ Update user (`/api/console/update-user`)
**Quando usar**: Testes que envolvem edição de perfil ou wizard.
***
### `setupTemplateMocks(page, options?)`
[Seção intitulada “setupTemplateMocks(page, options?)”](#setuptemplatemockspage-options)
Mocks relacionados a templates:
* ✅ Template details (public)
* ✅ Template installation
* ✅ Template list
**Opções**:
```typescript
{
templateId?: string,
templateSlug?: string,
templateName?: string,
planId?: string | null, // null = FREE, string = PAID
planPrice?: number | null,
couponId?: string | null,
isInstalled?: boolean
}
```
**Exemplo - Template FREE**:
```typescript
await setupTemplateMocks(page, {
templateSlug: "free-template",
planId: null,
});
```
**Exemplo - Template PAID**:
```typescript
await setupTemplateMocks(page, {
templateSlug: "premium-template",
planId: "plan-premium",
planPrice: 9900,
couponId: "WELCOME50",
});
```
***
### `setupPaymentMocks(page, options?)`
[Seção intitulada “setupPaymentMocks(page, options?)”](#setuppaymentmockspage-options)
Mocks de pagamento (Stripe):
* ✅ Setup intent
* ✅ Payment method attach
* ✅ Create subscription
**Opções**:
```typescript
{
setupIntentSecret?: string,
paymentMethodId?: string,
subscriptionId?: string,
shouldFailPayment?: boolean // Simular erro de pagamento
}
```
**Exemplo - Pagamento com sucesso**:
```typescript
await setupPaymentMocks(page);
```
**Exemplo - Simular falha**:
```typescript
await setupPaymentMocks(page, {
shouldFailPayment: true,
});
```
***
### `setupTrackingMocks(page)`
[Seção intitulada “setupTrackingMocks(page)”](#setuptrackingmockspage)
Mocks de analytics/tracking:
* ✅ Track events (`/api/*/track`)
* ✅ Identify (`/api/*/identify`)
**Quando usar**: Sempre (já incluído em `setupTemplateFlowMocks`).
***
### `setupTemplateFlowMocks(page, options?)`
[Seção intitulada “setupTemplateFlowMocks(page, options?)”](#setuptemplateflowmockspage-options)
**Helper all-in-one** que combina todos os mocks acima. **Use este para testes de template**.
Inclui:
* ✅ Common API mocks
* ✅ Auth mocks
* ✅ Profile mocks
* ✅ Template mocks
* ✅ Payment mocks
* ✅ Tracking mocks
**Opções**: Mesmas de `setupTemplateMocks()`.
**Exemplo**:
```typescript
test.beforeEach(async ({ page }) => {
await setupTemplateFlowMocks(page, {
templateSlug: "my-template",
planId: "plan-123",
});
});
```
## Exemplos Práticos
[Seção intitulada “Exemplos Práticos”](#exemplos-práticos)
### Teste de Template Gratuito
[Seção intitulada “Teste de Template Gratuito”](#teste-de-template-gratuito)
```typescript
import { setupTemplateFlowMocks } from "../helpers";
test.describe("Free Template Flow", () => {
test.beforeEach(async ({ page }) => {
await setupTemplateFlowMocks(page, {
templateId: "free-123",
templateSlug: "free-template",
planId: null, // FREE
});
});
test("should install free template", async ({ page }) => {
// Teste aqui...
});
});
```
### Teste de Template Pago
[Seção intitulada “Teste de Template Pago”](#teste-de-template-pago)
```typescript
import { setupTemplateFlowMocks } from "../helpers";
test.describe("Paid Template Flow", () => {
test.beforeEach(async ({ page }) => {
await setupTemplateFlowMocks(page, {
templateId: "paid-123",
templateSlug: "premium-template",
planId: "plan-premium",
planPrice: 9900,
});
});
test("should show checkout", async ({ page }) => {
// Teste aqui...
});
});
```
### Teste com Erro de Login
[Seção intitulada “Teste com Erro de Login”](#teste-com-erro-de-login)
```typescript
import { setupCommonApiMocks, setupAuthMocks } from "../helpers";
test.describe("Login Errors", () => {
test.beforeEach(async ({ page }) => {
await setupCommonApiMocks(page);
await setupAuthMocks(page, {
invalidCredentials: ["wrong@example.com"],
});
});
test("should show error for invalid credentials", async ({ page }) => {
// Teste aqui...
});
});
```
### Customizando Tracking
[Seção intitulada “Customizando Tracking”](#customizando-tracking)
```typescript
import { setupTemplateFlowMocks } from "../helpers";
test.beforeEach(async ({ page }) => {
const trackedEvents: any[] = [];
await setupTemplateFlowMocks(page, {
templateSlug: "test-template",
});
// Override tracking para capturar eventos
await page.route("**/api/*/track", async (route) => {
const data = route.request().postDataJSON();
trackedEvents.push(data);
await route.fulfill({ status: 200, body: "{}" });
});
});
```
## Boas Práticas
[Seção intitulada “Boas Práticas”](#boas-práticas)
### ✅ Fazer
[Seção intitulada “✅ Fazer”](#-fazer)
```typescript
// ✅ Usar helpers pré-configurados
await setupTemplateFlowMocks(page, { templateSlug: "test" });
// ✅ Customizar apenas o necessário
await setupAuthMocks(page, { invalidCredentials: ["bad@test.com"] });
// ✅ Setup modular quando não precisa de tudo
await setupCommonApiMocks(page);
await setupAuthMocks(page);
```
### ❌ Evitar
[Seção intitulada “❌ Evitar”](#-evitar)
```typescript
// ❌ Não criar mocks manualmente
await page.route('**/api/console/login', async (route) => {
await route.fulfill({ ... }); // Use setupAuthMocks() em vez disso
});
// ❌ Não duplicar código entre testes
test.beforeEach(async ({ page }) => {
// 50 linhas de mocks manuais... ❌
});
```
## Estendendo os Helpers
[Seção intitulada “Estendendo os Helpers”](#estendendo-os-helpers)
Se precisar de novos mocks, **adicione no arquivo `api-mocks.ts`**:
```typescript
export const setupMyNewMocks = async (page: Page) => {
await page.route("**/api/my-endpoint", async (route) => {
await createJsonResponse(route, { data: "test" });
});
};
```
## Referências
[Seção intitulada “Referências”](#referências)
* [Playwright Route Mocking](https://playwright.dev/docs/network#handle-requests)
* [Utilitários Compartilhados](/frontend/testing/utils/shared) - Fixtures compartilhadas
# E2E
> Testes End-to-End com Playwright
Este diretório contém os testes End-to-End (E2E) da aplicação Gaio Console usando Playwright.
> 📚 **Documentação completa**: Veja [Arquitetura de Testes](/frontend/testing/overview/) para arquitetura geral e guias de testes.
## Estrutura
[Seção intitulada “Estrutura”](#estrutura)
```plaintext
e2e/
├── pages/ # Page Objects (seguindo o Page Object Model)
│ ├── base.page.ts # Classe base com funcionalidades comuns
│ ├── register.page.ts
│ ├── verify-email-*.page.ts
│ ├── forgot-password-*.page.ts
│ ├── reset-password.page.ts
│ ├── accept-invite.page.ts
│ ├── template-preview.page.ts
│ ├── template-install-login.page.ts
│ ├── template-install-contact.page.ts
│ ├── template-install-wizard-profile.page.ts
│ ├── template-install-wizard-discovery.page.ts
│ ├── template-install-checkout.page.ts
│ └── template-install-activation.page.ts
├── specs/ # Arquivos de teste
│ ├── signup-verify-email.spec.ts
│ ├── forgot-password.spec.ts
│ ├── accept-invite.spec.ts
│ ├── template-install-free.spec.ts # Testes de instalação de template gratuito
│ └── template-install-paid.spec.ts # Testes de instalação de template pago
└── README.md
```
## Como Executar
[Seção intitulada “Como Executar”](#como-executar)
### Pré-requisitos
[Seção intitulada “Pré-requisitos”](#pré-requisitos)
Instale os browsers do Playwright (apenas necessário na primeira vez):
```bash
npx playwright install
```
### Executar Testes
[Seção intitulada “Executar Testes”](#executar-testes)
```bash
# Executar todos os testes E2E
npm run test:e2e
# Executar com interface visual
npm run test:e2e:ui
# Executar em modo debug
npm run test:e2e:debug
# Ver relatório após execução
npm run test:e2e:report
# Code generator (para criar novos testes)
npm run test:e2e:codegen
```
### Executar do Diretório Raiz
[Seção intitulada “Executar do Diretório Raiz”](#executar-do-diretório-raiz)
```bash
# Do diretório raiz do monorepo
npm run test:e2e # Roda testes em todos os workspaces
npm run test:e2e:ui # Roda com UI em todos os workspaces
```
## Page Object Model
[Seção intitulada “Page Object Model”](#page-object-model)
Os testes seguem o padrão **Page Object Model (POM)**, onde cada página da aplicação tem uma classe correspondente que encapsula:
* Seletores de elementos
* Ações (click, fill, etc.)
* Verificações específicas da página
## API Mocks Padronizados
[Seção intitulada “API Mocks Padronizados”](#api-mocks-padronizados)
Todos os testes E2E devem usar os **helpers de API mocks** para garantir consistência. Veja [helpers/api-mocks.ts](./helpers/api-mocks.ts).
### Exemplo Básico
[Seção intitulada “Exemplo Básico”](#exemplo-básico)
```typescript
import { setupTemplateFlowMocks } from '../helpers';
test.beforeEach(async ({ page }) => {
// Setup completo de mocks para fluxo de template
await setupTemplateFlowMocks(page, {
templateId: 'template-123',
templateSlug: 'test-template',
planId: null // FREE template
});
});
```
### Exemplo Avançado (Customizado)
[Seção intitulada “Exemplo Avançado (Customizado)”](#exemplo-avançado-customizado)
```typescript
import { setupCommonApiMocks, setupAuthMocks, setupTemplateMocks } from '../helpers';
test.beforeEach(async ({ page }) => {
// Setup modular de mocks
await setupCommonApiMocks(page);
await setupAuthMocks(page, {
invalidCredentials: ['invalid@example.com'],
existingEmails: ['existing@example.com']
});
await setupTemplateMocks(page, {
templateId: 'my-template',
planId: 'plan-123',
planPrice: 9900
});
});
```
### Helpers Disponíveis
[Seção intitulada “Helpers Disponíveis”](#helpers-disponíveis)
| Helper | Descrição |
| -------------------------- | ------------------------------------------ |
| `setupCommonApiMocks()` | Mocks básicos (user, connections, account) |
| `setupAuthMocks()` | Login, signup, email verification |
| `setupProfileMocks()` | Update de perfil e contato |
| `setupTemplateMocks()` | Templates e instalação |
| `setupPaymentMocks()` | Stripe, subscriptions |
| `setupTrackingMocks()` | Analytics e tracking |
| `setupTemplateFlowMocks()` | **Tudo acima** (fluxo completo) |
Veja documentação completa em [helpers/api-mocks.ts](./helpers/api-mocks.ts).
### Exemplo
[Seção intitulada “Exemplo”](#exemplo)
```typescript
import { ForgotPasswordRequestPage } from '../pages/forgot-password-request.page';
test('should submit email', async ({ page }) => {
const requestPage = new ForgotPasswordRequestPage(page);
await requestPage.goto();
await requestPage.submitEmail('user@example.com');
// Página navega automaticamente para /verify
});
```
## Browsers Suportados
[Seção intitulada “Browsers Suportados”](#browsers-suportados)
Os testes rodam em múltiplos browsers e viewports:
* **Desktop**: Chromium, Firefox, WebKit (Safari)
* **Mobile**: Chrome (Pixel 5), Safari (iPhone 12)
Para rodar apenas em um browser específico:
```bash
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
```
## Configuração
[Seção intitulada “Configuração”](#configuração)
A configuração está em [playwright.config.ts](../playwright.config.ts).
### Principais Configurações
[Seção intitulada “Principais Configurações”](#principais-configurações)
* **baseURL**: `http://localhost:5173`
* **Retry**: 2 vezes apenas no CI
* **Screenshot**: Capturado apenas em falhas
* **Trace**: Coletado apenas no primeiro retry
* **Video**: Mantido apenas em falhas
* **Dev Server**: Inicia automaticamente com `npm run serve`
## Escrevendo Novos Testes
[Seção intitulada “Escrevendo Novos Testes”](#escrevendo-novos-testes)
1. **Criar Page Object** (se necessário):
e2e/pages/my-page.page.ts
```typescript
import { BasePage } from './base.page';
export class MyPage extends BasePage {
readonly myButton: Locator;
constructor(page: Page) {
super(page);
this.myButton = page.getByRole('button', { name: /my button/i });
}
async clickMyButton() {
await this.myButton.click();
}
}
```
2. **Criar Teste**:
e2e/specs/my-feature.spec.ts
```typescript
import { test, expect } from '@playwright/test';
import { MyPage } from '../pages/my-page.page';
test('should do something', async ({ page }) => {
const myPage = new MyPage(page);
await myPage.goto('/my-path');
await myPage.clickMyButton();
await expect(myPage.myButton).toBeDisabled();
});
```
## Dicas
[Seção intitulada “Dicas”](#dicas)
* Use `test.only()` para rodar apenas um teste específico
* Use `test.skip()` para pular um teste temporariamente
* Use `page.pause()` para debug interativo
* Use code generator para gerar seletores: `npm run test:e2e:codegen`
## Testes de Template Installation
[Seção intitulada “Testes de Template Installation”](#testes-de-template-installation)
Os testes de instalação de templates cobrem o fluxo completo de instalação de templates **gratuitos** e **pagos**:
### Fluxo de Template Gratuito (`template-install-free.spec.ts`)
[Seção intitulada “Fluxo de Template Gratuito (template-install-free.spec.ts)”](#fluxo-de-template-gratuito-template-install-freespects)
Testa o fluxo sem checkout:
1. Preview do template
2. Login/Autenticação
3. Informações de contato
4. Wizard de perfil
5. Wizard de discovery + consentimento
6. Ativação automática (sem pagamento)
7. Sucesso
**Eventos de tracking validados:**
* `template_viewed`
* `template_install_clicked`
* `auth_started`, `auth_completed`
* `profile_viewed`, `profile_completed`
* `checkout_submitted`, `checkout_completed` (sem `checkout_viewed`)
* `success_viewed`
* `funnel_abandoned` (quando aplicável)
### Fluxo de Template Pago (`template-install-paid.spec.ts`)
[Seção intitulada “Fluxo de Template Pago (template-install-paid.spec.ts)”](#fluxo-de-template-pago-template-install-paidspects)
Testa o fluxo com checkout: 1-5. Mesmos passos do fluxo gratuito 6. **Checkout** (formulário de pagamento Stripe) 7. Ativação após pagamento 8. Sucesso
**Eventos de tracking adicionais:**
* `checkout_viewed` (apenas para templates pagos)
* `checkout_error` (em caso de falha no pagamento)
* Todas as propriedades incluem `is_paid: true`, `plan_id`, `coupon_id`
### Executar apenas testes de template
[Seção intitulada “Executar apenas testes de template”](#executar-apenas-testes-de-template)
```bash
# Apenas templates gratuitos
npx playwright test template-install-free
# Apenas templates pagos
npx playwright test template-install-paid
# Todos os testes de template
npx playwright test template-install
```
## Documentação
[Seção intitulada “Documentação”](#documentação)
* [Playwright Docs](https://playwright.dev)
* [Page Object Model](https://playwright.dev/docs/pom)
* [Best Practices](https://playwright.dev/docs/best-practices)
# Visão Geral
> Estrutura e organização (Vitest vs Playwright)
Estrutura organizada para evitar conflitos entre frameworks de teste (Vitest vs Playwright).
## Estrutura
[Seção intitulada “Estrutura”](#estrutura)
```plaintext
packages/console/
├── test-shared/ # ✅ Utils compartilhados (SEM dependências de framework)
│ ├── fixtures/ # Dados fixos (tokens, users, ids)
│ └── factories/ # Criadores de objetos
│
├── test-utils/ # 🧪 Utils específicos do Vitest
│ ├── handlers/ # MSW handlers
│ ├── middlewares/ # MSW middlewares
│ └── server.ts # MSW server setup
│
└── e2e/ # 🎭 Testes Playwright
├── pages/ # Page Objects
└── specs/ # Testes E2E
```
## Regras de Importação
[Seção intitulada “Regras de Importação”](#regras-de-importação)
### ✅ Permitido
[Seção intitulada “✅ Permitido”](#-permitido)
```typescript
// Testes Vitest podem importar de:
import { TOKENS } from "../../test-shared"; // ✅ Shared
import { mswServer } from "../../test-utils"; // ✅ Vitest utils
// Testes Playwright podem importar de:
import { TOKENS } from "../../test-shared"; // ✅ Shared
import { LoginPage } from "../pages/login"; // ✅ Page Objects
```
### ❌ Proibido (causa conflitos)
[Seção intitulada “❌ Proibido (causa conflitos)”](#-proibido-causa-conflitos)
```typescript
// ❌ Playwright NÃO deve importar de test-utils (tem dependências Vitest)
import { mswServer } from "../../test-utils"; // ❌ ERRO!
// ❌ Vitest NÃO deve importar de e2e/pages (são Page Objects do Playwright)
import { LoginPage } from "../../e2e/pages"; // ❌ ERRO!
```
## Framework Agnostic
[Seção intitulada “Framework Agnostic”](#framework-agnostic)
**Propósito**: Utils compartilhados sem dependências externas de testes.
**Características**:
* ✅ Zero dependências de frameworks de teste
* ✅ Apenas JavaScript/TypeScript puro
* ✅ Importável por Vitest E Playwright
* ✅ Fixtures simples e factories leves
**Conteúdo**:
test-shared/fixtures/tokens.ts
```typescript
export const TOKENS = {
valid: () => generateMockToken(),
expired: () => generateMockToken(expiredTime),
};
// test-shared/factories/user.ts
export const createUser = (overrides = {}) => ({
id: "test-user",
name: "Test User",
...overrides,
});
```
## Vitest Específico
[Seção intitulada “Vitest Específico”](#vitest-específico)
**Propósito**: Setup e mocks específicos do Vitest (MSW, etc).
**Características**:
* Apenas para testes Vitest
* Pode ter dependências pesadas (MSW, faker, etc)
* Inclui server MSW e handlers HTTP
* Setup de testes de integração
**Conteúdo**:
test-utils/server.ts
```typescript
import { setupServer } from "msw/node";
export const mswServer = setupServer(...handlers);
// test-utils/handlers/auth.handlers.ts
export const authHandlers = [
http.post("/api/login", () => {
return HttpResponse.json({ token: TOKENS.valid() });
}),
];
```
## Playwright Específico
[Seção intitulada “Playwright Específico”](#playwright-específico)
**Propósito**: Testes End-to-End com Playwright.
**Características**:
* Testa fluxos completos da aplicação
* Page Object Model
* Foca em interação do usuário
* Usa `test-shared/` para fixtures
**Conteúdo**:
e2e/pages/login.page.ts
```typescript
export class LoginPage extends BasePage {
async login(email, password) { ... }
}
// e2e/specs/login.spec.ts
test('should login', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login('user@test.com', 'pass');
});
```
## Por que essa separação?
[Seção intitulada “Por que essa separação?”](#por-que-essa-separação)
### Problema Anterior
[Seção intitulada “Problema Anterior”](#problema-anterior)
```plaintext
❌ Testes Playwright importavam de `test-utils/`
↓
`test-utils/` tinha dependências Vitest (MSW com Vitest)
↓
Playwright carregava código do Vitest
↓
CONFLITO: "Cannot redefine Symbol($$jest-matchers-object)"
```
### Solução Atual
[Seção intitulada “Solução Atual”](#solução-atual)
```plaintext
✅ Testes Playwright importam de `test-shared/`
↓
`test-shared/` NÃO tem dependências de framework
↓
Playwright carrega apenas código puro
✅ SEM CONFLITOS
```
## Checklist ao Criar Utils
[Seção intitulada “Checklist ao Criar Utils”](#checklist-ao-criar-utils)
Antes de adicionar algo em `test-shared/`:
* [ ] É framework-agnostic? (sem `vitest`, `@playwright/test`, `msw`)
* [ ] É simples? (sem lógica complexa)
* [ ] Será usado por Vitest E Playwright?
* [ ] Não tem dependências externas pesadas?
Se qualquer resposta for **NÃO**, coloque em:
* `test-utils/` se for específico do Vitest
* `e2e/` se for específico do Playwright
## Exemplos de Uso
[Seção intitulada “Exemplos de Uso”](#exemplos-de-uso)
### Criar novo token fixture
[Seção intitulada “Criar novo token fixture”](#criar-novo-token-fixture)
test-shared/fixtures/tokens.ts
```typescript
export const TOKENS = {
admin: () => generateMockToken({ role: "admin" }),
};
```
### Criar handler MSW
[Seção intitulada “Criar handler MSW”](#criar-handler-msw)
test-utils/handlers/templates.handlers.ts
```typescript
export const templateHandlers = [
http.get("/api/templates", () => {
return HttpResponse.json([createTemplate()]);
}),
];
```
### Criar Page Object
[Seção intitulada “Criar Page Object”](#criar-page-object)
e2e/pages/template.page.ts
```typescript
export class TemplatePage extends BasePage {
async installTemplate() { ... }
}
```
## Documentação
[Seção intitulada “Documentação”](#documentação)
* [Utilitários Compartilhados](/frontend/testing/utils/shared) - Utils compartilhados
* [Testes Playwright](/frontend/testing/e2e) - Testes Playwright
* [Utils Vitest](/frontend/testing/utils/overview) - Utils Vitest (se existir)
# Vitest / MSW
Utilitários específicos para testes **Vitest** (unitários e de integração) usando **Mock Service Worker (MSW)** para interceptação de requisições HTTP.
> **Documentação completa**: [Arquitetura de Testes](/frontend/testing/overview) **Importante**: Estes utils contêm dependências do Vitest e **NÃO devem** ser importados em testes Playwright. Use os [Utilitários Compartilhados](/frontend/testing/utils/shared) para código compartilhado.
## Estrutura
[Seção intitulada “Estrutura”](#estrutura)
```plaintext
test-utils/
├── handlers/ # MSW handlers para interceptar APIs
│ └── auth.ts # Handlers de autenticação
├── middlewares/ # MSW middlewares customizados
├── helpers/ # Helpers específicos do Vitest
├── fixtures/ # Fixtures específicos do Vitest
├── factories/ # Factories com dependências Vitest
├── server.ts # Setup do MSW server
└── index.ts # Exportações centralizadas
```
## Uso
[Seção intitulada “Uso”](#uso)
### Setup MSW no Vitest
[Seção intitulada “Setup MSW no Vitest”](#setup-msw-no-vitest)
O MSW server é configurado automaticamente no `vitest.setup.tsx`:
```typescript
import { beforeAll, afterAll, afterEach } from "vitest";
import { mswServer } from "./test-utils";
// Inicia o server antes de todos os testes
beforeAll(() => mswServer.listen({ onUnhandledRequest: "error" }));
// Reseta handlers após cada teste
afterEach(() => mswServer.resetHandlers());
// Para o server após todos os testes
afterAll(() => mswServer.close());
```
### Renderizar componente com React Query
[Seção intitulada “Renderizar componente com React Query”](#renderizar-componente-com-react-query)
```typescript
import { render, screen } from '@/test-utils';
import { MyComponent } from './my-component';
describe('MyComponent', () => {
it('should fetch and display data', async () => {
render();
// MSW intercepta automaticamente as requests
expect(await screen.findByText('Data loaded')).toBeInTheDocument();
});
});
```
### Customizar handlers por teste
[Seção intitulada “Customizar handlers por teste”](#customizar-handlers-por-teste)
```typescript
import { render, screen } from '@/test-utils';
import { mswServer } from '@/test-utils';
import { http, HttpResponse } from 'msw';
describe('MyComponent with errors', () => {
it('should handle API errors', async () => {
// Override handler apenas para este teste
mswServer.use(
http.get('/api/data', () => {
return HttpResponse.json({ error: 'Failed' }, { status: 500 });
})
);
render();
expect(await screen.findByText('Error occurred')).toBeInTheDocument();
});
});
```
## Handlers Disponíveis
[Seção intitulada “Handlers Disponíveis”](#handlers-disponíveis)
Os handlers estão organizados por domínio em `handlers/`:
* **auth.ts**: Login, signup, logout, token refresh
* *(Adicione novos handlers conforme necessário)*
## Boas Práticas
[Seção intitulada “Boas Práticas”](#boas-práticas)
### ✅ Fazer
[Seção intitulada “✅ Fazer”](#-fazer)
```typescript
// ✅ Importar de test-utils em testes Vitest
import { render, mswServer } from "@/test-utils";
import { TOKENS } from "@/test-shared"; // Shared é OK
```
### ❌ NÃO Fazer
[Seção intitulada “❌ NÃO Fazer”](#-não-fazer)
```typescript
// ❌ Importar test-utils em testes Playwright
import { mswServer } from "../../test-utils"; // ERRO!
// ❌ Importar Page Objects do Playwright aqui
import { LoginPage } from "../../e2e/pages/login"; // ERRO!
```
## Adicionar Novos Handlers
[Seção intitulada “Adicionar Novos Handlers”](#adicionar-novos-handlers)
1. Crie um arquivo em `handlers/` (ex: `handlers/user.ts`)
2. Exporte os handlers:
handlers/user.ts
```typescript
import { http, HttpResponse } from "msw";
export const userHandlers = [
http.get("/api/console/current-user", () => {
return HttpResponse.json({
id: "user-123",
email: "test@example.com",
name: "Test User",
});
}),
http.patch("/api/console/profile", async ({ request }) => {
const body = await request.json();
return HttpResponse.json({ ...body, updated: true });
}),
];
```
3. Registre no `server.ts`:
server.ts
```typescript
import { setupServer } from "msw/node";
import { authHandlers } from "./handlers/auth";
import { userHandlers } from "./handlers/user"; // Novo
export const mswServer = setupServer(
...authHandlers,
...userHandlers, // Adiciona aqui
);
```
## Troubleshooting
[Seção intitulada “Troubleshooting”](#troubleshooting)
### Requests não estão sendo interceptadas
[Seção intitulada “Requests não estão sendo interceptadas”](#requests-não-estão-sendo-interceptadas)
**Problema**: Componente faz request mas MSW não intercepta.
**Solução**:
1. Verifique se o handler está registrado no `server.ts`
2. Confirme que o URL do handler corresponde exatamente à request
3. Verifique se `mswServer.listen()` foi chamado no setup
### Erro “Cannot redefine property”
[Seção intitulada “Erro “Cannot redefine property””](#erro-cannot-redefine-property)
**Problema**: Erro ao rodar testes Playwright.
**Solução**: Você está importando `test-utils` em testes Playwright. Use apenas `test-shared` em testes E2E.
### Handler não está sendo aplicado
[Seção intitulada “Handler não está sendo aplicado”](#handler-não-está-sendo-aplicado)
**Problema**: Override com `mswServer.use()` não funciona.
**Solução**:
* Use `mswServer.use()` ANTES de renderizar o componente
* Se ainda não funcionar, use `mswServer.resetHandlers()` antes
## 📖 Links Úteis
[Seção intitulada “📖 Links Úteis”](#-links-úteis)
* [MSW Documentation](https://mswjs.io/)
* [Vitest](https://vitest.dev/guide/)
* [React Testing Library](https://testing-library.com/react)
* [Arquitetura de Testes](/frontend/testing/overview)
# Compartilhados
> Utilitários de teste compartilhados entre Vitest e Playwright
Utilitários de teste **compartilhados** e **independentes de framework**, que podem ser usados tanto nos testes do **Vitest** quanto do **Playwright**.
> **Documentação completa**: [Arquitetura de Testes](/frontend/testing/overview)
## Objetivo
[Seção intitulada “Objetivo”](#objetivo)
Evitar conflitos entre frameworks de teste mantendo fixtures e factories sem dependências externas de teste (Vitest, Playwright, MSW, etc).
## Estrutura
[Seção intitulada “Estrutura”](#estrutura)
```plaintext
test-shared/
├── fixtures/ # Dados fixos para testes
│ ├── ids.ts # IDs de teste consistentes
│ ├── tokens.ts # Geração de tokens mock
│ └── users.ts # Usuários pré-configurados
├── factories/ # Criadores de objetos de teste
│ └── user.ts # Factory de usuários
└── index.ts # Exportações centralizadas
```
## Uso
[Seção intitulada “Uso”](#uso)
### Em testes do Playwright (E2E)
[Seção intitulada “Em testes do Playwright (E2E)”](#em-testes-do-playwright-e2e)
```typescript
import { TOKENS, createUser, TEST_IDS } from "../../test-shared";
test("should authenticate", async ({ page }) => {
await page.route("**/api/login", async (route) => {
await route.fulfill({
body: JSON.stringify({
access_token: TOKENS.valid(),
refresh_token: TOKENS.refresh(),
}),
});
});
});
```
### Em testes do Vitest (Unit/Integration)
[Seção intitulada “Em testes do Vitest (Unit/Integration)”](#em-testes-do-vitest-unitintegration)
```typescript
import { TOKENS, createUser } from "../../test-shared";
describe("Auth Service", () => {
it("should parse token", () => {
const token = TOKENS.valid();
expect(parseToken(token)).toBeDefined();
});
});
```
## Disponível
[Seção intitulada “Disponível”](#disponível)
### Fixtures
[Seção intitulada “Fixtures”](#fixtures)
* **`TOKENS`**: Gerador de tokens JWT mock
* `TOKENS.valid()` - Token válido por 1h
* `TOKENS.expired()` - Token expirado
* `TOKENS.refresh()` - Refresh token
* `TOKENS.impersonate.valid()` - Token de impersonação
* **`TEST_IDS`**: IDs consistentes para testes
* `TEST_IDS.users.default` - ID do usuário padrão
* `TEST_IDS.accounts.default` - ID da conta padrão
* **`TEST_USERS`**: Usuários pré-configurados
* `TEST_USERS.default` - Usuário padrão
* `TEST_USERS.admin` - Usuário admin
### Factories
[Seção intitulada “Factories”](#factories)
* **`createUser(overrides?)`**: Cria usuário com valores padrão
```typescript
const user = createUser({ name: "Custom Name" });
```
## 🚫 O que NÃO colocar aqui
[Seção intitulada “🚫 O que NÃO colocar aqui”](#-o-que-não-colocar-aqui)
* ❌ Setups do MSW (vai em `test-utils/`)
* ❌ Configurações do Vitest (vai em `vitest.config.ts`)
* ❌ Page Objects do Playwright (vai em `e2e/pages/`)
* ❌ Dependências externas pesadas (faker, etc)
## ✅ O que colocar aqui
[Seção intitulada “✅ O que colocar aqui”](#-o-que-colocar-aqui)
* ✅ Fixtures simples e estáticas
* ✅ Factories sem dependências externas
* ✅ Constantes de teste
* ✅ Geradores de dados mock simples
* ✅ Tipos compartilhados para testes
## Diferença entre `test-shared/` e `test-utils/`
[Seção intitulada “Diferença entre test-shared/ e test-utils/”](#diferença-entre-test-shared-e-test-utils)
| Aspecto | `test-shared/` | `test-utils/` |
| ------------------ | ------------------- | ------------------- |
| **Framework** | Agnóstico | Específico Vitest |
| **Dependências** | Nenhuma | MSW, Vitest, etc |
| **Uso** | Vitest + Playwright | Apenas Vitest |
| **Conteúdo** | Fixtures, Factories | Handlers MSW, Setup |
| **Importável por** | Qualquer teste | Só testes Vitest |
## Boas Práticas
[Seção intitulada “Boas Práticas”](#boas-práticas)
1. **Mantenha simples**: Sem lógica complexa ou dependências externas
2. **Seja consistente**: Use sempre os mesmos IDs/valores nos testes
3. **Documente**: Adicione JSDoc explicando o propósito de cada fixture
4. **Exporte tudo**: Use `index.ts` para exportações centralizadas
5. **Evite estado**: Factories devem ser funções puras quando possível