Debugging

Debug Mode

A primeira ferramenta para troubleshooting é ativar o modo debug.

Ativar Debug

<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    debug: true // ou process.env.NODE_ENV === 'development'
  }}
>

Logs que Você Verá

[Testly] 🚀 SDK initialized
[Testly] 🔑 API Key: testly_abc...xyz (valid)
[Testly] ✅ Experiment loaded: homepage-hero-test
[Testly] 👤 User ID: user_123abc
[Testly] 🎲 Assigned variant: variant-b
[Testly] 📊 Impression recorded
[Testly] 🎯 Conversion recorded: cta_clicked
[Testly] ❌ API ERROR: 401 Unauthorized

Recomendação: Sempre desenvolva com debug: true. Isso economiza horas de troubleshooting.

Problemas Comuns e Soluções

1. Nada Acontece / Variante Sempre Null

Sintomas:

const { variant } = useExperiment('test');
console.log(variant); // null

Possíveis Causas:

API Key inválida ou ausente

Como verificar:

console.log(process.env.NEXT_PUBLIC_TESTLY_API_KEY); // undefined?

Solução:

Verifique se o arquivo .env.local existe
Certifique-se de usar o prefixo correto:
- Next.js: NEXT_PUBLIC_
- Vite: VITE_
Reinicie o servidor de desenvolvimento
Verifique no dashboard se a API Key está ativa

.env.local

# ✅ Correto (Next.js)
NEXT_PUBLIC_TESTLY_API_KEY=testly_abc123...

# ❌ Errado (falta prefixo)
TESTLY_API_KEY=testly_abc123...

Experimento não existe ou está inativo

Como verificar:

Acesse o dashboard
Procure pelo experimentId usado no código
Verifique se está marcado como “Ativo”

Solução:

Crie o experimento no dashboard
Ative o experimento
Use o ID exato (case-sensitive)

// ✅ Correto
useExperiment('homepage-hero-test')

// ❌ Errado (ID diferente)
useExperiment('homepage-hero')
useExperiment('HomePage-Hero-Test')

Provider não está envolvendo o componente

Como verificar:

// No seu componente
const { variant } = useExperiment('test');
// Se der erro "useExperiment must be used within TestlyProvider"

Solução: Certifique-se de que o TestlyProvider está em um nível superior:

// ✅ Correto
<TestlyProvider apiKey="...">
  <App>
    <MyComponent /> {/* pode usar useExperiment */}
  </App>
</TestlyProvider>

// ❌ Errado
<App>
  <MyComponent /> {/* NÃO pode usar useExperiment */}
  <TestlyProvider apiKey="...">
    ...
  </TestlyProvider>
</App>

Erro de rede / Timeout

Como verificar: Abra DevTools → Network → Procure por chamadas para api.testly.comPossíveis problemas:

❌ Request bloqueado por CORS
❌ Firewall corporativo bloqueando
❌ Timeout (resposta demorada)
❌ API fora do ar

Solução:

// Aumentar timeout
<TestlyProvider 
  config={{
    timeout: 10000 // 10 segundos
  }}
/>

// Ou verificar status da API
// https://status.testly.com

2. Loading Nunca Termina

Sintomas:

const { loading } = useExperiment('test');
console.log(loading); // sempre true

Diagnóstico:

useEffect(() => {
  console.log('Loading state:', loading);
  console.log('Variant:', variant);
  console.log('Error:', error);
}, [loading, variant, error]);

Soluções:

Timeout muito curto

<TestlyProvider 
  config={{
    timeout: 8000 // Aumentar para 8s
  }}
/>

API está fora

Verifique o status: https://status.testly.comImplemente fallback:

const { variant, loading } = useExperiment('test');

useEffect(() => {
  const timer = setTimeout(() => {
    if (loading) {
      console.error('Loading timeout - usando fallback');
      // Usar versão padrão
    }
  }, 10000);

  return () => clearTimeout(timer);
}, [loading]);

Problema de cache infinito

Limpar cache manualmente:

// No console do navegador
localStorage.clear();
location.reload();

Ou desativar cache temporariamente:

<TestlyProvider 
  config={{
    cacheEnabled: false // Apenas para debug
  }}
/>

3. Conversões Não São Registradas

Sintomas:

const { convert } = useExperiment('test');
convert('clicked'); // Nada acontece no dashboard

Diagnóstico com Debug:

const { convert } = useExperiment('test');

const handleClick = async () => {
  try {
    console.log('Chamando convert...');
    await convert('clicked');
    console.log('✅ Conversão registrada!');
  } catch (error) {
    console.error('❌ Erro:', error);
  }
};

Possíveis Causas:

Impressão não foi registrada primeiro

Problema: Conversões só contam se o usuário VIU o experimento antes.Como verificar:

const { variant, loading } = useExperiment('test');

// Se loading for true, impressão ainda não foi registrada
if (!loading && variant) {
  // Agora pode converter
  convert('clicked');
}

Solução: Sempre aguarde o loading terminar:

const { variant, loading, convert } = useExperiment('test');

if (loading) return <Skeleton />;

return (
  <button onClick={() => convert('clicked')}>
    Clique Aqui
  </button>
);

Nome do evento inválido

Problema: Nome muito longo ou caracteres especiaisSolução:

// ✅ Bom
convert('button_clicked')
convert('form_submitted')
convert('trial_started')

// ❌ Ruim
convert('Botão Principal da Homepage Clicado!!!') // Muito longo
convert('clique@botão') // Caracteres especiais
convert('') // Vazio

Deduplicação está ativa

Problema: Você chamou convert() duas vezes na mesma sessão

convert('clicked'); // ✅ Registrada
convert('clicked'); // ❌ Ignorada (dedupe)

Solução:

Use nomes diferentes para eventos diferentes
Ou desative dedupe (não recomendado)

<TestlyProvider 
  config={{
    dedupConversions: false // Permite duplicatas
  }}
/>

API Key sem permissão de escrita

Problema: Sua API Key pode estar configurada como “read-only”Solução:

Acesse o dashboard
Vá em Configurações → API Keys
Certifique-se que tem permissão de escrita
Gere uma nova key se necessário

4. Variante Muda a Cada Refresh

Sintomas:

Refresh 1: variant-a
Refresh 2: variant-b
Refresh 3: variant-a

Isso NÃO deveria acontecer! O Testly garante consistência. Possíveis Causas:

Cache está desativado

Verificar:

<TestlyProvider 
  config={{
    cacheEnabled: true // Deve ser true (padrão)
  }}
/>

localStorage está sendo limpo

Verificar: Algum código está limpando localStorage?

// Procure por isso no seu código
localStorage.clear(); // ❌ Remove cache do Testly

// Ou limpe apenas o que você precisa
localStorage.removeItem('minha-chave'); // ✅ Específico

Navegação privada/anônima

Problema: Navegação anônima limpa cookies/storage ao fecharSolução: Isso é esperado em modo anônimo. Para testar, use navegação normal.

userId diferente sendo gerado

Problema: Se você passa userId customizado e ele muda

// ❌ Ruim - userId muda a cada render
const { variant } = useExperiment('test', {
  userId: Math.random().toString()
});

// ✅ Bom - userId consistente
const userId = user?.id || 'anonymous';
const { variant } = useExperiment('test', { userId });

5. Erro: “useExperiment must be used within TestlyProvider”

Sintoma:

Error: useExperiment must be used within TestlyProvider

Causa: Hook sendo usado fora do Provider Solução:

// ❌ Errado
function App() {
  const { variant } = useExperiment('test'); // Erro!
  
  return (
    <TestlyProvider apiKey="...">
      <Component />
    </TestlyProvider>
  );
}

// ✅ Correto
function App() {
  return (
    <TestlyProvider apiKey="...">
      <Component /> {/* useExperiment aqui dentro */}
    </TestlyProvider>
  );
}

function Component() {
  const { variant } = useExperiment('test'); // ✅ OK
  return <div>{variant}</div>;
}

6. TypeScript: Tipos Não Reconhecidos

Sintoma:

Cannot find module '@testly/react' or its corresponding type declarations

Soluções:

Reinstalar pacote

rm -rf node_modules package-lock.json
npm install

Verificar tsconfig.json

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Criar types declaration (workaround)

types/testly.d.ts

declare module '@testly/react' {
  export function TestlyProvider(props: any): JSX.Element;
  export function useExperiment(id: string, options?: any): any;
  export function useConversion(): any;
}

Ferramentas de Debugging

1. DevTools Network Tab

O que procurar:

Request URL: https://api.testly.com/v1/variants/assign
Method: POST
Status: 200 OK

Request Payload:
{
  "experimentId": "homepage-hero-test",
  "userId": "user_123"
}

Response:
{
  "success": true,
  "data": {
    "variantId": "variant-b"
  }
}

Status codes importantes:

Status	Significado	Solução
`200 OK`	✅ Sucesso	Tudo certo
`401 Unauthorized`	❌ API Key inválida	Verificar key
`404 Not Found`	❌ Experimento não existe	Verificar ID
`429 Too Many Requests`	❌ Rate limit	Aguardar ou aumentar plano
`500 Server Error`	❌ Erro no servidor	Contactar suporte

2. React DevTools

Verificar Provider:

Abra React DevTools
Procure por TestlyProvider na árvore de componentes
Verifique as props:
- apiKey está presente?
- config está correto?

Verificar estado do hook:

Selecione componente que usa useExperiment
Veja os hooks na sidebar
Verifique valores:
- variant
- loading
- error

3. Console Logs Customizados

function DebugExperiment() {
  const { variant, loading, error, convert } = useExperiment('test');

  useEffect(() => {
    console.group('🔍 Testly Debug');
    console.log('Variant:', variant);
    console.log('Loading:', loading);
    console.log('Error:', error);
    console.log('Experiment ID:', 'test');
    console.log('Timestamp:', new Date().toISOString());
    console.groupEnd();
  }, [variant, loading, error]);

  return <div>{variant}</div>;
}

4. Verificar localStorage

// No console do navegador
Object.keys(localStorage)
  .filter(key => key.startsWith('testly-'))
  .forEach(key => {
    console.log(key, localStorage.getItem(key));
  });

// Output:
// testly-experiment-homepage-hero-test: {"variantId":"variant-b","userId":"user_123"}
// testly-impression-homepage-hero-test-variant-b: true

Checklist de Troubleshooting

Quando algo não funciona, siga esta ordem:

Ativar Debug Mode

config={{ debug: true }}

Verificar Console

Procure por erros vermelhos ou logs [Testly]

Verificar Network Tab

Há requests para api.testly.com? Qual o status?

Verificar Dashboard

Experimento existe? Está ativo?

Verificar API Key

Está no .env? Tem o prefixo correto? Servidor foi reiniciado?

Verificar Provider

Está envolvendo o componente correto?

Limpar Cache

localStorage.clear();
location.reload();

Testar em Navegação Anônima

Elimina problemas de cache/extensões

Casos Extremos

Next.js: Hydration Mismatch

Sintoma:

Warning: Text content did not match. Server: "variant-a" Client: "variant-b"

Causa: Servidor e cliente renderizam variantes diferentes Solução:

'use client'; // Forçar client-side

function MyComponent() {
  const { variant, loading } = useExperiment('test');
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted || loading) {
    return <Skeleton />; // Sempre renderiza igual no servidor
  }

  return <div>{variant}</div>; // Apenas cliente vê variante
}

React Strict Mode (Double Render)

Sintoma: Logs aparecem duas vezes em desenvolvimento Causa: React 18 Strict Mode renderiza componentes duas vezes Solução: Isso é normal em desenvolvimento. Ignore ou desative Strict Mode:

// ❌ Strict Mode (desenvolvimento)
<React.StrictMode>
  <App />
</React.StrictMode>

// ✅ Sem Strict Mode (apenas se necessário)
<App />

CORS em Localhost

Sintoma:

CORS policy: No 'Access-Control-Allow-Origin' header

Solução: Use localhost ao invés de 127.0.0.1 ou configure proxy:

next.config.js

module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/testly/:path*',
        destination: 'https://api.testly.com/v1/:path*'
      }
    ];
  }
};

Precisa de Ajuda?

Se nenhuma solução funcionou:

Discord

Comunidade ativa de devs

Email

[email protected]

GitHub Issues

Reporte bugs

Status Page

Verificar se API está no ar

Ao pedir ajuda, inclua:

- Versão do SDK: 1.x.x
- Framework: Next.js 14 / React 18
- Comportamento esperado vs atual
- Logs do debug mode
- Network tab screenshot (se relevante)
- Código relevante (remova API key!)

Próximos Passos

Best Practices

Metodologias de experimentação

Configuração

Opções avançadas do SDK

useExperiment

Documentação do hook principal

Exemplos

Veja implementações práticas

Email

Primeiros Passos

SDK

Guias

Debug Mode

Ativar Debug

Logs que Você Verá

Problemas Comuns e Soluções

1. Nada Acontece / Variante Sempre Null

2. Loading Nunca Termina

3. Conversões Não São Registradas

4. Variante Muda a Cada Refresh

5. Erro: “useExperiment must be used within TestlyProvider”

6. TypeScript: Tipos Não Reconhecidos

Ferramentas de Debugging

1. DevTools Network Tab

2. React DevTools

3. Console Logs Customizados

4. Verificar localStorage

Checklist de Troubleshooting

Casos Extremos

Next.js: Hydration Mismatch

React Strict Mode (Double Render)

CORS em Localhost

Precisa de Ajuda?

Discord

GitHub Issues

Status Page

Próximos Passos

Best Practices

Configuração

useExperiment

Exemplos

Primeiros Passos

SDK

Guias

​Debug Mode

​Ativar Debug

​Logs que Você Verá

​Problemas Comuns e Soluções

​1. Nada Acontece / Variante Sempre Null

​2. Loading Nunca Termina

​3. Conversões Não São Registradas

​4. Variante Muda a Cada Refresh

​5. Erro: “useExperiment must be used within TestlyProvider”

​6. TypeScript: Tipos Não Reconhecidos

​Ferramentas de Debugging

​1. DevTools Network Tab

​2. React DevTools

​3. Console Logs Customizados

​4. Verificar localStorage

​Checklist de Troubleshooting

​Casos Extremos

​Next.js: Hydration Mismatch

​React Strict Mode (Double Render)

​CORS em Localhost

​Precisa de Ajuda?

Discord

Email

GitHub Issues

Status Page

​Próximos Passos

Best Practices

Configuração

useExperiment

Exemplos

Debug Mode

Ativar Debug

Logs que Você Verá

Problemas Comuns e Soluções

1. Nada Acontece / Variante Sempre Null

2. Loading Nunca Termina

3. Conversões Não São Registradas

4. Variante Muda a Cada Refresh

5. Erro: “useExperiment must be used within TestlyProvider”

6. TypeScript: Tipos Não Reconhecidos

Ferramentas de Debugging

1. DevTools Network Tab

2. React DevTools

3. Console Logs Customizados

4. Verificar localStorage

Checklist de Troubleshooting

Casos Extremos

Next.js: Hydration Mismatch

React Strict Mode (Double Render)

CORS em Localhost

Precisa de Ajuda?

Próximos Passos