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, tie up server threads or workers, and often trigger async processing (virus scans, image resizing, format conversion) that is a separate latency budget. Load-testing the upload path separately from the rest of your API reveals these characteristics.

Test type: Load test or Stress test.

Prerequisites

• A MaxoPerf account and workspace.
• A representative sample file (image, PDF, CSV) that you want to upload. Size it realistically — a 1 KB file does not exercise the upload path meaningfully.
• 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

You need to include the sample file alongside 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 typically have latencies in the hundreds of milliseconds or seconds, not the tens-of-ms you see for JSON API calls.
3. Watch throughput (RPS) — with a large file and slow server, RPS will be low (e.g. 2–10 RPS per VU thread).

Verify

• The POST /upload label shows 2xx responses consistently.
• Latency is stable across the run (no progressive increase, which would indicate thread pool saturation on the server).
• Error rate is near zero — 413 Payload Too Large errors indicate a server-side file-size limit; 504 Gateway Timeout indicates upstream timeout before the upload completes.
• 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 understand how latency scales with payload.
• Multipart with additional fields: add extra form fields by including them as key-value pairs in the body section alongside the upload-files block.
• JMeter: use the HTTP Request sampler with 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 manages 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.