File upload multipart test

import { Steps, Aside } from ‘@astrojs/starlight/components’;

Problem: File upload endpoints are slow and stateful. They hold a connection open while the full payload transfers and tie up server threads or workers. They often trigger async processing (virus scans, image resizing, format conversion) with its own latency budget. Load-test the upload path separately from the rest of your API to see this behaviour.

Test type: Load test or Stress test.

Prerequisites

• A MaxoPerf account and workspace.
• A representative sample file (image, PDF, CSV) to upload. Give it a realistic size. A 1 KB file does not put real work on the upload path.
• Knowledge of the expected Content-Type, form field names, and any authentication the upload endpoint requires.

Uploading many files creates real storage costs and backend processing on the target system. Use a staging environment with object-storage lifecycle policies (e.g. auto-delete after 1 hour) so test uploads do not accumulate indefinitely.

Step by step in MaxoPerf

1. Upload the sample file as a test data file

Include the sample file next to your Taurus YAML so MaxoPerf can inject it into the runner.

1. Open the test, switch to the Files tab.
2. Upload both upload-test.yml (the YAML you will write below) and sample.pdf (the file to upload).
3. Mark upload-test.yml as the entrypoint. Leave sample.pdf as a supporting file.
4. Save.

See Upload test files for the entrypoint / supporting-file distinction.

2. Write the Taurus scenario

execution:
  - scenario: file-upload
    concurrency: 10
    ramp-up: 1m
    hold-for: 5m

scenarios:
  file-upload:
    requests:
      - label: POST /upload
        url: https://app.example.com/upload
        method: POST
        headers:
          Authorization: Bearer ${UPLOAD_TOKEN}
        upload-files:
          - param: file
            path: sample.pdf
            mime-type: application/pdf

The upload-files block maps the form field name (file) to the local path of the uploaded file (sample.pdf). Taurus constructs the multipart/form-data request automatically.

3. Bind the auth secret

1. Switch to Settings → Secrets and bind UPLOAD_TOKEN.
2. Save.

4. Run the test

1. Click Run now from the Configuration tab.
2. Watch the p95 latency in the run overview. Upload endpoints usually take hundreds of milliseconds or whole seconds, compared with the tens of ms you see for JSON API calls.
3. Watch throughput (RPS). With a large file and a slow server, RPS stays low (e.g. 2–10 RPS per VU thread).

Verify

• The POST /upload label shows 2xx responses consistently.
• Latency is stable across the run. A steady climb points to thread pool saturation on the server.
• Error rate is near zero. 413 Payload Too Large means a server-side file-size limit. 504 Gateway Timeout means an upstream timeout hit before the upload completed.
• If you see high error rates at low concurrency, the server’s upload endpoint has a concurrency or rate limit.

Variations

• Multiple file sizes: create three tests with different file sizes (1 MB, 10 MB, 50 MB) to see how latency scales with payload.
• Multipart with additional fields: add extra form fields as key-value pairs in the body section next to the upload-files block.
• JMeter: use the HTTP Request sampler with the Files Upload tab for multipart. See JMeter JMX on Maxoperf.
• Post-upload processing: if the server returns a job ID for async processing, correlate the job ID and poll a status endpoint. See Correlation and dynamic values.

Where to go next

• Upload test files: how the Files tab handles entrypoints and supporting files.
• REST API CRUD load test: test the full lifecycle around an upload (create upload → poll status → retrieve result).
• Load test: what this test type measures and how to read the results.