Load Testing File Uploads with k6 — Performance Testing Guide

File upload is often the performance bottleneck in web applications. This guide shows how to load test your upload endpoint with k6 using real sample files from TrueFileSize.

Prerequisites

• k6 installed (brew install k6 or choco install k6)
• Sample files downloaded from TrueFileSize
• An upload API endpoint to test

Step 1: Download Test Files

mkdir -p test-files
curl -sL -o test-files/small.pdf https://cdn.truefilesize.com/pdf/sample-100kb.pdf
curl -sL -o test-files/medium.jpg https://cdn.truefilesize.com/jpg/sample-1mb.jpg
curl -sL -o test-files/large.mp4 https://cdn.truefilesize.com/mp4/sample-10mb.mp4

Available sizes: 100KB PDF · 1MB JPG · 10MB MP4 · 100MB test file

Step 2: Basic Upload Load Test

// upload-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';
import { Rate, Trend } from 'k6/metrics';

// Custom metrics
const uploadDuration = new Trend('upload_duration', true);
const uploadFailRate = new Rate('upload_failures');

// Load file once at init time (shared across VUs)
const smallFile = open('test-files/small.pdf', 'b');
const mediumFile = open('test-files/medium.jpg', 'b');

export const options = {
  stages: [
    { duration: '30s', target: 5 },   // Ramp up to 5 users
    { duration: '1m', target: 10 },   // Hold at 10 users
    { duration: '30s', target: 20 },  // Spike to 20 users
    { duration: '30s', target: 0 },   // Ramp down
  ],
  thresholds: {
    upload_duration: ['p(95)<5000'], // 95% of uploads under 5s
    upload_failures: ['rate<0.05'],  // Less than 5% failure rate
    http_req_duration: ['p(99)<10000'],
  },
};

export default function () {
  // Randomly pick file size
  const file = Math.random() > 0.5 ? mediumFile : smallFile;
  const fileName = Math.random() > 0.5 ? 'photo.jpg' : 'document.pdf';

  const data = {
    file: http.file(file, fileName),
  };

  const start = Date.now();
  const res = http.post('https://your-api.com/api/upload', data);
  uploadDuration.add(Date.now() - start);

  const success = check(res, {
    'status is 200 or 201': (r) => r.status === 200 || r.status === 201,
    'response has file URL': (r) => r.json('url') !== undefined,
    'response time < 5s': (r) => r.timings.duration < 5000,
  });

  uploadFailRate.add(!success);
  sleep(1);
}

Step 3: Run the Test

# Basic run
k6 run upload-test.js

# With more output
k6 run --out json=results.json upload-test.js

# Override target URL
k6 run -e API_URL=https://staging.your-api.com upload-test.js

Step 4: Large File Upload Test

// large-upload-test.js
import http from 'k6/http';
import { check } from 'k6';

const largeFile = open('test-files/large.mp4', 'b');

export const options = {
  vus: 3,  // Fewer VUs for large files
  duration: '2m',
  thresholds: {
    http_req_duration: ['p(95)<30000'], // 30s for 10MB files
  },
};

export default function () {
  const res = http.post('https://your-api.com/api/upload', {
    file: http.file(largeFile, 'video.mp4', 'video/mp4'),
  }, {
    timeout: '60s',
  });

  check(res, {
    'upload succeeded': (r) => r.status === 200,
    'under 30 seconds': (r) => r.timings.duration < 30000,
  });
}

Step 5: Analyze Results

k6 outputs these key metrics:

| Metric | What It Means | Target | |--------|--------------|--------| | http_req_duration | Total request time | p95 < 5s (small files) | | upload_duration | Custom upload time | p95 < 10s | | upload_failures | Error rate | < 5% | | http_reqs | Throughput (req/s) | Depends on infra | | vus | Concurrent users | Ramp up until failure |

Expected Performance Benchmarks

| File Size | 10 VUs | 50 VUs | 100 VUs | |-----------|--------|--------|---------| | 100 KB | <500ms | <1s | <2s | | 1 MB | <1s | <3s | <5s | | 10 MB | <5s | <15s | Timeout risk | | 100 MB | <30s | Not recommended | Don't |

Tips

1. Start small: Test with 100KB files first, then increase size
2. Ramp gradually: Don't jump to 100 VUs — k6 stages let you ramp
3. Use thresholds: Set pass/fail criteria before running
4. Test your CDN too: Download speed tests with our Download Tests page
5. Monitor server-side: Watch CPU, memory, and disk I/O during the test

All sample files: TrueFileSize — PDF · JPG · MP4 · Download Tests