Teste Técnico Python: Checklist para Vagas no Brasil

Teste técnico Python não é só uma prova de sintaxe. Em muitos processos seletivos no Brasil, ele funciona como uma amostra de como você trabalha quando recebe um problema incompleto, precisa tomar decisões e entregar algo que outra pessoa consiga rodar. O código importa, mas a experiência do avaliador também pesa: instalação, README, testes, organização e clareza sobre limites.

Este checklist ajuda você a preparar, executar e revisar um desafio técnico de Python sem transformar uma tarefa pequena em um projeto gigante. Ele complementa o guia de perguntas de entrevista Python e o roteiro de currículo Python para vaga júnior.

Antes de começar o desafio

Leia o enunciado como se fosse uma especificação de produto. Marque entradas, saídas, regras obrigatórias, restrições de tempo e critérios explícitos de avaliação. Se o teste pede uma API, confirme endpoints, formatos de resposta e status HTTP esperados. Se pede dados, identifique origem, tamanho, encoding, campos obrigatórios e exemplos de linhas inválidas.

Antes de escrever código, responda quatro perguntas:

• qual é a menor entrega que resolve o pedido principal?
• quais casos de erro precisam ser tratados?
• como o avaliador vai rodar isso em uma máquina limpa?
• quais decisões precisam aparecer no README?

Essa etapa evita dois erros comuns: entregar algo sofisticado que não atende ao enunciado ou gastar horas em arquitetura antes de resolver o fluxo principal.

Estrutura mínima recomendada

Para a maioria dos testes, uma estrutura simples é suficiente:

desafio-python/
  README.md
  pyproject.toml
  src/
    desafio_python/
      __init__.py
      main.py
      service.py
  tests/
    test_service.py
  .env.example

Se o desafio for apenas um script de linha de comando, você pode reduzir. Se envolver FastAPI, banco ou fila, adicione app.py, models.py, repositories.py ou docker-compose.yml apenas quando forem necessários. Evite criar camadas vazias para parecer enterprise.

Ambiente reproduzível

O avaliador não deve adivinhar como instalar dependências. Escolha uma forma e documente:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Se usar uv, explique também:

uv sync
uv run pytest
uv run desafio-python

Inclua versão mínima do Python, por exemplo Python 3.12+, e evite depender de variáveis locais sem .env.example. Nunca coloque token real, senha, URL privada ou dado sensível no repositório.

README que passa confiança

Um README bom não precisa ser longo. Ele precisa responder rapidamente:

• o que o projeto faz;
• como instalar;
• como rodar;
• como executar testes;
• quais decisões técnicas foram tomadas;
• quais limitações existem;
• o que você faria com mais tempo.

Exemplo de seção final útil:

## Decisões e limitações

- Usei SQLite para facilitar a execução local do avaliador.
- Validei os campos de entrada com Pydantic para evitar dados incompletos.
- Não implementei autenticação porque o enunciado não pedia.
- Com mais tempo, adicionaria paginação, logs estruturados e teste de carga simples.

Isso mostra maturidade sem prometer mais do que você entregou.

Testes que realmente ajudam

Você não precisa cobrir 100% do código em um desafio curto. Cubra o comportamento principal e os erros mais prováveis. Em um teste de API, inclua ao menos:

• caso feliz;
• entrada inválida;
• recurso não encontrado;
• regra de negócio crítica;
• serialização da resposta.

Em um teste de dados, inclua:

• linha válida;
• campo ausente;
• tipo inválido;
• duplicidade;
• cálculo principal.

Se o tempo estiver curto, é melhor ter poucos testes relevantes do que muitos testes frágeis que só verificam implementação interna.

Checklist por tipo de desafio

API com FastAPI ou Django

Para APIs, o avaliador costuma olhar organização, validação e semântica HTTP. Garanta:

• endpoints com nomes previsíveis;
• status code correto;
• validação de entrada;
• mensagens de erro úteis;
• testes com cliente HTTP;
• instrução clara para subir localmente;
• exemplo de curl ou payload JSON no README.

Se usar FastAPI, Pydantic ajuda a deixar contrato explícito. Se usar Django, explique rapidamente por que escolheu Django REST Framework, class-based views ou function-based views.

Dados, ETL ou análise

Para desafios de dados, o problema muitas vezes está nos detalhes: CSV com acento, data brasileira, decimal com vírgula, duplicidades ou campos vazios. Cuide de:

• encoding (utf-8 quando possível);
• timezone e formato de data;
• validação de colunas obrigatórias;
• tratamento de linhas inválidas;
• resultado reproduzível;
• separação entre extração, transformação e saída.

Se o teste permitir, salve amostras pequenas em tests/fixtures/. Não suba bases grandes sem necessidade.

Automação ou scraping

Desafios de scraping aparecem em vagas de dados, growth e operações. Mostre responsabilidade:

• respeite robots.txt quando aplicável;
• configure timeout;
• trate erro HTTP;
• limite paginação;
• não faça requisições infinitas;
• salve progresso se o processo for longo;
• explique limites legais e éticos no README.

Para estudar a base técnica, veja web scraping com Python e HTTPX como alternativa moderna ao Requests.

Erros que eliminam candidatos

Alguns problemas passam uma mensagem ruim mesmo quando o algoritmo está correto:

• projeto que não roda com as instruções do README;
• dependência ausente ou versão não fixada;
• caminho absoluto da sua máquina;
• token real no código;
• exceção genérica escondendo erro importante;
• ausência total de teste;
• commit único com mensagem vaga, quando o repositório pede histórico;
• resposta fora do formato solicitado;
• solução muito maior que o problema.

Antes de enviar, clone seu próprio projeto em outra pasta ou apague o ambiente virtual e rode tudo de novo seguindo apenas o README. Esse teste simples pega muitos problemas.

Como explicar trade-offs

O avaliador não espera perfeição infinita. Ele espera decisões coerentes com tempo e escopo. Use frases objetivas:

• “Escolhi SQLite porque o desafio precisava rodar localmente sem infraestrutura externa.”
• “Separei a transformação em função pura para facilitar testes.”
• “Não adicionei cache porque não havia requisito de volume ou latência.”
• “Usei paginação simples e limite máximo para evitar loop infinito em API externa.”

Esse tipo de explicação mostra que você sabe equilibrar entrega, manutenção e risco.

Revisão final antes de enviar

Use esta lista nos últimos 20 minutos:

• pytest roda limpo;
• comando principal roda do zero;
• README tem instalação, execução e testes;
• .env.example existe se houver configuração;
• dados sensíveis não foram versionados;
• lint ou formatação foram aplicados se configurados;
• nomes de arquivos e funções estão claros;
• há pelo menos um teste para erro;
• limitações estão documentadas;
• o link do repositório está acessível.

Se você travar em algo, não esconda. Documente o problema, mostre a parte funcional e diga como investigaria. Em processos brasileiros, uma entrega honesta e reproduzível costuma valer mais do que uma solução ambiciosa que só roda na sua máquina.

Próximos passos

Depois de preparar seu checklist, pratique com um projeto pequeno do seu portfólio. Pegue uma API pública brasileira, crie uma transformação simples, escreva testes e documente tudo como se fosse um case. Isso conecta preparação de entrevista com material real para currículo e GitHub.

Para continuar, leia também Projetos de Portfólio Python para Conseguir Vaga, Testes com pytest e Boas Práticas Python 2026.