typed-pytest: Recuperando o autocompletar da IDE e a segurança de tipos perdidos no MagicMock

Ao escrever código de teste com Pytest e usar MagicMock, muita gente provavelmente já passou pela experiência de não ter autocompletar na IDE ou de perder tempo por ter digitado o nome de um método errado.

Os mocks existentes são muito poderosos, mas as dicas de tipo se perdem, o que dificulta aproveitar a ajuda de verificadores de tipo como mypy ou pyright. Para resolver isso, foi criado o typed-pytest, que oferece mocking com segurança de tipos (type-safe mocking).

Principais recursos:

• Autocompletar completo na IDE: suporta autocompletar não só para nomes de métodos e parâmetros da classe real, mas também para métodos específicos de mock como assert_called_once_with.
• Detecção de erros de digitação em tempo de lint: se você chamar um método inexistente ou passar argumentos incorretos, o erro é detectado imediatamente antes de executar os testes (via mypy/pyright).
• Gerador dedicado de stubs: analisa as classes do projeto e gera automaticamente arquivos de dica de tipo (.pyi). (Também oferece suporte a classes com dependências externas, como FastAPI e SQLAlchemy)
• Backend flexível: se quiser mais velocidade, pode usar inspect; se precisar de dicas de tipo de retorno mais precisas, pode escolher o backend stubgen. (No momento, stubgen está em fase experimental)

Exemplo de uso:

# MagicMock tradicional: mesmo com erro de digitação, não dá para saber antes da execução  
mock = MagicMock(spec=UserService)  
mock.get_usr(1) # erro de digitação de get_user, mas o linter não detecta  
  
# typed-pytest: o linter gera erro imediatamente e oferece autocompletar  
from typed_pytest_stubs import typed_mock, UserService  
  
mock = typed_mock(UserService)  
mock.get_usr # ❌ Error: "get_usr" is not a member of UserService  
mock.get_user.assert_called_once_with(user_id=1) # ✅ verificação de tipos concluída  

Os arquivos de stub gerados foram projetados para serem usados apenas no ambiente local de desenvolvimento e no CI, sem necessidade de enviá-los ao Git. A compatibilidade com ferramentas modernas como uv também foi considerada.

GitHub: https://github.com/tmdgusya/typed-pytest

Espero que isso ajude quem quer aproveitar plenamente os benefícios do sistema de tipos também no código de testes. Feedback para melhorar a usabilidade é sempre bem-vindo!!