DEV Community

Cover image for Como Testar APIs de Upload de Arquivos (multipart/form-data) no Apidog
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Testar APIs de Upload de Arquivos (multipart/form-data) no Apidog

Você criou um endpoint que recebe arquivos: um usuário envia uma foto para POST /avatars ou seu aplicativo envia um PDF assinado para POST /documents. Agora é preciso testar o fluxo via HTTP: selecionar um arquivo real, anexá-lo a um campo do formulário, enviar a requisição e validar a resposta.

Experimente o Apidog hoje

Uploads exigem alguns cuidados porque usam multipart/form-data, não JSON. Você precisa configurar corretamente os campos de arquivo e, ao automatizar testes, garantir que o arquivo exista na máquina onde o cenário será executado.

O Apidog permite montar e testar essas requisições. Neste guia, você vai:

  • enviar um único arquivo;
  • enviar arquivo e JSON na mesma requisição;
  • validar a resposta;
  • executar uploads em cenários, Runner e CLI;
  • evitar erros de caminho de arquivo em automações.

Para entender a estrutura do protocolo, consulte o guia sobre upload de arquivos em APIs e a referência do MDN sobre FormData.

O que é multipart/form-data e por que uploads precisam dele

Uma requisição HTTP pode enviar corpo em vários formatos: form-data, x-www-form-urlencoded, JSON, XML, raw ou binário. Para a maioria dos endpoints, JSON resolve. Para uploads, use form-data.

Ao selecionar form-data, a requisição usa:

Content-Type: multipart/form-data
Enter fullscreen mode Exit fullscreen mode

Esse formato divide o corpo em partes independentes. Cada parte possui nome e conteúdo próprios:

  • uma parte pode ser uma string, como title;
  • outra pode conter os bytes de uma imagem ou PDF;
  • todas são enviadas na mesma requisição.

Por exemplo, um upload de avatar pode incluir o arquivo e uma legenda:

avatar: jane-profile.png
caption: Foto do perfil
Enter fullscreen mode Exit fullscreen mode

Não confunda form-data com x-www-form-urlencoded:

Formato Use quando
multipart/form-data Há arquivos, imagens, PDFs ou outros bytes no corpo
x-www-form-urlencoded Há apenas campos escalares curtos, sem arquivos

No Apidog, cada parâmetro de form-data possui um tipo. O ponto principal é mudar o tipo do campo que receberá o anexo para file. Assim, o Apidog envia o conteúdo do arquivo, não apenas um texto com seu nome ou caminho.

Envie um único arquivo e valide a resposta

Considere o endpoint:

POST /avatars
Enter fullscreen mode Exit fullscreen mode

Ele recebe um campo avatar com uma imagem e retorna informações sobre o arquivo armazenado.

1. Configure o método, URL e corpo

No Apidog:

  1. Defina o método como POST.
  2. Informe a URL do endpoint, por exemplo: 
   https://api.example.com/avatars
Enter fullscreen mode Exit fullscreen mode
  1. Abra a aba Body.
  2. Selecione form-data.

O Apidog define o Content-Type: multipart/form-data para a requisição.

2. Crie o campo de arquivo

Adicione uma linha de parâmetro:

Chave Tipo
avatar file

Mude o tipo de string para file. O campo de valor passa a oferecer um seletor de arquivo.

3. Selecione o arquivo local

Clique em Upload na linha avatar e selecione um arquivo local, por exemplo:

jane-profile.png
Enter fullscreen mode Exit fullscreen mode

O Apidog registra o caminho local do arquivo para usar ao enviar a requisição.

Importante: o Apidog envia o arquivo, mas não armazena seus bytes na nuvem. O que fica salvo é o caminho local. Isso afeta execuções em outra máquina, Runner e CLI.

4. Envie a requisição

Clique em Send. Uma resposta bem-sucedida pode ser semelhante a:

{
  "id": "usr_8842",
  "avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
  "sizeBytes": 48210,
  "contentType": "image/png"
}
Enter fullscreen mode Exit fullscreen mode

5. Adicione validações

Um status 200 sozinho não garante que o upload funcionou corretamente. Valide também os dados retornados.

Exemplo de validações pós-requisição:

status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Enter fullscreen mode Exit fullscreen mode

No Apidog, configure:

  1. uma validação para o código de status;
  2. uma validação JSONPath para confirmar que $.avatarUrl existe;
  3. uma validação para confirmar o valor de $.contentType.

Para mais operadores e exemplos de JSONPath, consulte o guia de validações de API.

O equivalente em curl seria:

curl -X POST https://api.example.com/avatars \
  -F "avatar=@jane-profile.png"
Enter fullscreen mode Exit fullscreen mode

A flag -F cria uma parte multipart. O prefixo @ instrui o curl a ler o conteúdo do arquivo local.

Envie arquivo e JSON na mesma requisição

Endpoints reais normalmente recebem mais do que um arquivo. Por exemplo:

POST /documents
Enter fullscreen mode Exit fullscreen mode

Esse endpoint pode esperar:

  • um PDF;
  • um título;
  • uma categoria;
  • tags;
  • outros metadados.

Campos simples: use parâmetros separados

Para valores escalares, adicione campos form-data adicionais:

Chave Tipo Exemplo
file file q3-invoice.pdf
title string Q3 Invoice
category string billing

Todos os campos serão enviados na mesma requisição multipart.

Metadados estruturados: envie JSON como string

Se os metadados incluem objetos aninhados ou arrays, crie um campo metadata do tipo string e cole o JSON no valor:

{
  "title": "Q3 Invoice",
  "category": "billing",
  "tags": ["invoice", "2026", "paid"]
}
Enter fullscreen mode Exit fullscreen mode

A requisição passa a ter duas partes principais:

file: q3-invoice.pdf
metadata: {"title":"Q3 Invoice","category":"billing","tags":["invoice","2026","paid"]}
Enter fullscreen mode Exit fullscreen mode

O servidor lê o arquivo em uma parte e interpreta o JSON na outra. Esse padrão é comum em APIs multipart, incluindo o endpoint descrito na documentação de upload de arquivos do Stripe.

Se você está migrando do Postman, consulte o guia sobre como fazer upload de um arquivo e dados JSON no Postman.

Envie múltiplos arquivos

Para anexar mais de um arquivo, adicione mais parâmetros do tipo file.

Exemplo para um endpoint que recebe um documento e sua miniatura:

Chave Tipo
file file
thumbnail file

Cada campo terá seu próprio botão Upload. Não existe um modo especial para múltiplos anexos: crie uma linha para cada parte esperada pela API.

Transforme o upload em um cenário de teste repetível

Enviar uma requisição manualmente confirma apenas que o endpoint funcionou uma vez. Para detectar regressões, salve o fluxo como um cenário de teste.

Um fluxo típico seria:

  1. enviar POST /avatars;
  2. capturar o id da resposta;
  3. executar GET /users/{id};
  4. validar que avatarUrl foi persistido.

O guia sobre como escrever um cenário de teste com Apidog explica como encadear etapas e reutilizar valores retornados.

Depois de salvar o cenário, você pode:

Há um detalhe importante: o cenário funciona localmente porque o arquivo existe na sua máquina. Essa premissa deixa de valer quando a execução ocorre em outro ambiente.

A pegadinha: o arquivo precisa existir onde o teste roda

O Apidog salva o caminho do arquivo, não o arquivo em si.

Localmente, isso parece transparente:

/Users/jane/pics/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Mas esse caminho só é válido no computador da Jane. Se outra pessoa, um Runner ou uma máquina de CI tentar executar o cenário, esse arquivo não será encontrado.

Colaboração em equipe

Quando um colega abre sua requisição, ele pode ver o parâmetro avatar e o caminho salvo. Porém, ele não consegue enviar o arquivo se esse caminho apontar para seu disco local.

Para executar a requisição, o colega deve:

  1. ter uma cópia do arquivo na própria máquina;
  2. selecionar esse arquivo no campo de upload;
  3. usar um caminho válido para o ambiente dele.

Runner e CLI

O mesmo problema aparece em automação:

  • o cenário passa no laptop;
  • você agenda uma execução no Runner ou CI;
  • a etapa de upload falha porque o arquivo não existe no host de execução.

A solução é sempre a mesma:

  1. copie o arquivo para a máquina que executará o teste;
  2. use um caminho acessível nessa máquina;
  3. atualize o campo de arquivo ou use uma variável de ambiente.

Configure uploads no Runner

O Runner lê arquivos disponíveis em um diretório do host montado no volume durante a implantação, usando a flag -v.

Fluxo recomendado:

  1. Monte um diretório do host no volume do Runner.
  2. Copie o arquivo para esse diretório.
  3. Abra os detalhes da etapa de upload no cenário.
  4. Clique em Batch Edit.
  5. Atualize o caminho do campo de arquivo.

Exemplo:

/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

O arquivo precisa estar dentro do diretório montado. Se ele estiver fora da montagem, o Runner não conseguirá encontrá-lo, mesmo que o caminho pareça correto.

Consulte a documentação do Apidog sobre requisições de upload de arquivos para os detalhes de montagem e edição em massa.

Configure uploads na CLI

Na CLI, a regra é idêntica: o arquivo deve existir na máquina que executa o comando.

Por exemplo:

/opt/apidog/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Atualize o caminho da etapa usando Batch Edit ou, preferencialmente, uma variável.

Use uma variável para evitar caminhos fixos

Em vez de salvar um caminho literal na etapa, use uma variável para o caminho do arquivo.

Exemplo conceitual:

{{upload_file_path}}
Enter fullscreen mode Exit fullscreen mode

Defina valores diferentes por ambiente:

Ambiente Valor de upload_file_path
Local /Users/jane/pics/jane-profile.png
Runner /opt/runner/jane-profile.png
CI /opt/apidog/runner/jane-profile.png

Assim, o cenário continua o mesmo em todos os ambientes. Apenas o valor da variável muda.

Automatize cenários de upload com a CLI do Apidog

Depois de salvar o cenário, execute-o sem interface gráfica em uma pipeline de CI.

Instale a CLI e autentique-se:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Execute um cenário salvo por ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Parâmetros:

Parâmetro Descrição
-t ID do cenário de teste
-e ID do ambiente
-r Reporter: cli, html ou junit

Para múltiplos reporters, separe os valores por vírgula.

A CLI executa os cenários salvos no projeto e retorna códigos de saída que podem controlar o status da pipeline. Veja o guia de instalação da CLI do Apidog para os detalhes de configuração.

Antes de executar um cenário com upload na CI, confirme:

  • o arquivo foi copiado para o runner;
  • o caminho configurado é válido no runner;
  • a variável de caminho, caso exista, aponta para o local correto.

Para fluxos mais completos de CI, incluindo entradas por linha, consulte testes orientados a dados com a CLI do Apidog.

FAQ

Por que meu colega não consegue enviar minha requisição de upload?

Porque o Apidog salva o caminho local do arquivo, não o conteúdo do arquivo. Um caminho como:

/Users/jane/pics/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

só existe na máquina da Jane. Seu colega precisa ter uma cópia do arquivo e configurar um caminho válido na própria máquina.

O mesmo motivo explica por que testes agendados e execuções no Runner precisam preparar os arquivos antes de rodar o cenário.

Como envio JSON junto com um arquivo?

Use form-data:

  1. adicione o arquivo em um campo do tipo file;
  2. adicione outro campo do tipo string;
  3. cole o JSON nesse campo de texto.

O servidor receberá o arquivo em uma parte multipart e o JSON em outra.

Que caminho devo usar no Runner?

Use um caminho dentro do diretório montado com -v na implantação do Runner.

Exemplo:

/opt/runner/seuarquivo.jpg
Enter fullscreen mode Exit fullscreen mode

Copie o arquivo para esse diretório e atualize a etapa com Batch Edit. Para a CLI, um caminho pode ser:

/opt/apidog/runner/seuarquivo.jpg
Enter fullscreen mode Exit fullscreen mode

Existe limite de tamanho ou tipo de arquivo no Apidog?

Os limites efetivos dependem da API que você está testando. O Apidog constrói a requisição e lê o arquivo local; a validação de tamanho, extensão e MIME type é responsabilidade do servidor.

Teste explicitamente os casos esperados pela sua API:

  • arquivo válido;
  • tipo não permitido;
  • arquivo grande demais;
  • arquivo ausente;
  • metadados inválidos.

Devo usar form-data ou x-www-form-urlencoded?

Use form-data para uploads.

Ele usa multipart/form-data e transporta arquivos. Use x-www-form-urlencoded apenas para formulários simples sem arquivos.

Conclusão

Testar upload de arquivos exige duas verificações:

  1. a requisição multipart precisa estar configurada corretamente;
  2. o arquivo precisa estar disponível na máquina que executa o teste.

No Apidog, o fluxo é direto:

  1. selecione form-data;
  2. defina o campo de anexo como file;
  3. faça upload do arquivo;
  4. adicione campos extras ou JSON como string;
  5. envie a requisição;
  6. valide status e corpo da resposta;
  7. para Runner ou CLI, use caminhos acessíveis ou variáveis por ambiente.

Quer testar no seu endpoint? Baixe o Apidog, crie uma requisição form-data para sua rota de upload e valide a resposta.

Top comments (0)