Files let you ship data alongside your tests. When you upload a file in LoadForge, it is automatically made available on all runners for your team under the files/ directory, so your test code can open it directly.

​
What files are for

  • CSV datasets for data-driven scenarios
  • JSON config or fixtures
  • Text lists (e.g., usernames, URLs)
Files are team-scoped and synced to every worker. You do not need to upload them per region or run.

​
Where files live

  • Path on runners: files/{your_file_name}
  • Supported extensions: .csv, .json, .txt

​
Using files in Locust

​
CSV example

import csv
import random
from locust import HttpUser, task, between

class DataDrivenUser(HttpUser):
    wait_time = between(1, 3)

    def on_start(self):
        self.rows = []
        with open('files/test_data.csv', 'r') as f:
            reader = csv.DictReader(f)
            self.rows = list(reader)

    @task
    def submit(self):
        payload = random.choice(self.rows)
        self.client.post('/api/submit', payload)

​
JSON example

import json
from locust import HttpUser, task, between

class ConfigUser(HttpUser):
    wait_time = between(1, 5)

    def on_start(self):
        with open('files/config.json', 'r') as f:
            self.cfg = json.load(f)

    @task
    def call(self):
        for endpoint in self.cfg['endpoints']:
            self.client.get(endpoint['url'], name=endpoint['name'])

​
Best practices

  • Keep files reasonably small for fast sync
  • Load once in on_start rather than per request
  • Use structured formats (CSV/JSON) when possible
  • Validate rows and handle missing fields
  • See API: POST /api/v2/files to create files programmatically
  • See API: GET /api/v2/files to list files