Doctests
Doctests são exemplos de código em comentários de documentação /// que cargo test compila e executa. Eles mantêm a documentação honesta e demonstram o uso da API em linha com o rustdoc.
Receita
/// Adiciona dois inteiros.
///
/// ```
/// let sum = my_crate::add(2, 2);
/// assert_eq!(sum, 4);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}Quando usar isso: Exemplos de API pública que devem permanecer sincronizados com as alterações de código.
Exemplo Funcional
/// Analisa um ID de usuário a partir de texto.
///
/// # Erros
///
/// Retorna `Err` quando a entrada não é um inteiro positivo.
///
/// ```
/// use my_crate::parse_user_id;
///
/// let id = parse_user_id("42")?;
/// assert_eq!(id, 42);
/// # Ok::<(), my_crate::Error>(())
/// ```
pub fn parse_user_id(s: &str) -> Result<u64, Error> {
// ...
todo!()
}cargo test --doc
cargo test --doc parse_user_idO que isso demonstra:
- Exemplos são trechos completos de Rust que o rustdoc envolve em uma função (
fn). - O
?em exemplos precisa da linha oculta# Ok::<(), E>(())no final. cargo test --docexecuta apenas doctests.- Falhas apontam para a linha do comentário de documentação.
Mergulho Profundo
Atributos de Doctest
/// ```no_run
/// let client = Client::connect("postgres://...").await?;
/// ```
///
/// ```ignore
/// // pseudo-código não compilado
/// ```
///
/// ```should_panic
/// panic!("ruim");
/// ```| Marcador | Comportamento |
|---|---|
no_run | Compila, mas não executa |
ignore | Ignora a compilação (apenas exibe) |
should_panic | Espera pânico |
edition2024 | Define a edição para o trecho |
Linhas Ocultas
Prefira com # para ocultar a configuração da documentação renderizada:
/// ```
/// # use my_crate::Widget;
/// let w = Widget::default();
/// assert!(w.ready());
/// ```Armadilhas
- Ok oculto ausente para exemplos de Result - o doctest falha ao compilar. Correção: adicione
# Ok::<(), E>(())no final. - Exemplos assíncronos sem runtime - doctests são síncronos, a menos que use recursos instáveis de doctest
async. Correção: useno_runou mostre a API síncrona; vincule ao guia assíncrono. - Exemplos dependem do ambiente - CI instável. Correção: use mock ou strings fixas; evite rede em doctests.
- Muita configuração na documentação - saída renderizada barulhenta. Correção: oculte com linhas
#. ignoreem todos os lugares - exemplos decaem. Correção: prefira trechos compiláveis; reserveignorepara pseudocódigo.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
Diretório examples/ | Demonstrações executáveis de vários arquivos | Prova de API de uma linha |
| mdbook | Narrativa em formato de livro | rustdoc de API em linha |
| Testes de integração apenas | Aplicações Axum complexas | Funções puras simples |
FAQs
Itens privados recebem doctests?
Doctests são executados em itens públicos por padrão. A documentação de módulos privados pode ter doctests, mas não é exibida na documentação pública.
Como testar async em doctests?
Prefira no_run com um bloco async na documentação ou documente com um link para o teste de integração. Doctests async completos precisam de atributos noturnos.
Doctests podem importar crates externas?
Sim, se o crate for uma dependência; dev-deps não estão disponíveis para doctests na biblioteca.
Por que doctest vs. teste unitário?
Doctests documentam o uso; testes unitários cobrem casos extremos sem poluir a documentação pública.
Como desabilitar um doctest?
Use ```ignore ou remova o bloco de código; ou #[doc(hidden)] em APIs internas.
Workspaces executam todos os doctests?
cargo test --doc --workspace executa por crate; filtre com -p.
E APIs com #[cfg]?
Use ```cfg(feature = "foo") no bloco de código (cfg do rustdoc) para que os exemplos correspondam à documentação do recurso.
Como mostrar a saída stderr?
Doctests capturam a saída; use testes unitários para verificação de println! ou documente o comportamento esperado em prosa.
Posso nomear funções de doctest?
O Rustdoc envolve trechos em uma única função; divida em vários blocos de código para múltiplos cenários.
Como docs.rs executa doctests?
docs.rs compila a documentação; a execução do doctest acontece em seu CI via cargo test --doc.
Relacionados
- Noções Básicas de Teste -
cargo test - Testes Unitários vs. Integração - outros tipos de teste
- Lints de Documentação -
missing_docs - Melhores Práticas de Teste - política de teste de documentação
Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.