Get started with Artillery load testing

Model virtual-user arrivals, build data-driven request flows, and connect latency thresholds to server-side evidence.

Guance Editorial Team 4 min read Updated 2026-10-20

Illustration of software development and testing

Artillery describes load as a set of virtual-user arrivals and request flows. A YAML script defines the target, traffic phases, and each user's journey; the runner produces request and latency metrics. Use it to test capacity assumptions before a planned traffic increase, then compare the results with server-side telemetry.

A load test establishes behavior under its particular workload and environment. It does not predict every production failure or prove a fixed concurrency capacity simply because the script is short.

Test expected traffic before a peak

Monitoring reveals what the system is doing and can warn about developing problems. Load testing adds a controlled way to explore higher traffic before an event. Build a representative workload, increase it gradually, and observe both the target and the load generator. An arbitrary multiplier is less useful than a traffic model grounded in the application's actual request mix and user behavior.

Install Artillery and run a first test

Use a Node version supported by the Artillery release you install:

npm install -g artillery

Create load-test.yml:

config:
  target: 'http://localhost:3000'
  phases:
    - duration: 60
      arrivalRate: 20 # Start 20 virtual users per second.
scenarios:
  - name: 'Browse the home page'
    flow:
      - get:
          url: '/'

Run it against your local test server:

artillery run load-test.yml

Inspect request rate, latency percentiles, and errors. Tail percentiles such as p99 help identify slow requests, but need adequate samples and context about the endpoints and outcomes being measured.

Add traffic phases

Replace the config.phases list with:

phases:
  - duration: 120
    arrivalRate: 10  # Warm-up arrivals per second.
  - duration: 300
    arrivalRate: 50  # Sustained load.
  - duration: 60
    arrivalRate: 200
    rampTo: 400      # Ramp arrivals from 200 to 400 per second.

These are arrival rates, not fixed concurrent-user counts. Concurrency also depends on how long each journey takes. Look for changes in latency, errors, and resource saturation as the load increases; confirm the load generator itself still has capacity.

Model a data-driven user journey

CSV data belongs under config.payload. The following script registers a test user, logs in, captures a token, and sends an authenticated order request:

config:
  target: 'http://localhost:3000'
  phases:
    - duration: 10
      arrivalRate: 1
  payload:
    path: 'users.csv'
    fields: [username, password]
    skipHeader: true
    order: sequence
    cast: false
scenarios:
  - name: 'Register, log in, and order'
    flow:
      - post:
          url: '/api/register'
          json:
            username: '{{ username }}'
            password: '{{ password }}'
      - post:
          url: '/api/login'
          json:
            username: '{{ username }}'
            password: '{{ password }}'
          capture:
            - json: '$.token'
              as: 'authToken'
      - post:
          url: '/api/orders'
          headers:
            Authorization: 'Bearer {{ authToken }}'

Provide users.csv with a header and enough unique test accounts for the run. Sequential payload selection wraps after the last row, and distributed workers can reuse their own copies of the data. Avoid accidental duplicate registrations by planning the data allocation. Add whatever body fields your order endpoint requires. For generated values, use a supported hook such as beforeRequest.

Save reports and enforce CI thresholds

Include the script name when saving results:

artillery run --output report.json load-test.yml

The old artillery report report.json HTML command was removed in version 2.0.22. For current releases, retain the JSON result or use a supported reporting service such as Artillery Cloud.

Artillery integrations can export metrics to systems including Prometheus and Datadog. The expect plugin checks response expectations; the ensure plugin can fail the run when aggregate metrics exceed your limits. For example, add this under config to require response-time p99 to remain below 500 milliseconds:

plugins:
  ensure:
    thresholds:
      - 'http.response_time.p99': 500

In CI, deploy to a test environment, run a small load test, retain its results, and use explicit thresholds for the release decision. Tune the workload and limits to the service rather than treating this example threshold as a universal target.

Connect client latency to server bottlenecks

Rising load-test latency can come from the application or the generator. Include the test batch and service version in application logs, then compare request duration, errors, CPU use, and event-loop delay in Guance. Instrument the server for application performance monitoring (APM), and collect business metrics through an appropriate endpoint separately.

Compare the same request path at normal and higher load before deciding whether the next step is SQL optimization, scaling, or a concurrency change.

See Node.js APM instrumentation, Prometheus metric collection, and monitoring configuration.

Frequently asked questions

How does Artillery compare with k6 and JMeter?

Artillery offers YAML-defined flows and JavaScript extension points in a Node-based tool. k6 uses JavaScript for its scripts, while JMeter provides a Java-based tool with a GUI and broad protocol support. Compare required protocols, scripting, distributed execution, and operational constraints on a representative test. This article does not establish a performance ranking; Artillery itself also supports distributed load generation.

Could a test overload a production database?

Yes. Start in a representative nonproduction environment. A production test needs explicit operational coordination, bounded load, monitoring, stop conditions, and a rollback plan; read-only traffic can still saturate shared resources. Mark generated test data so it can be identified and cleaned up.

Are virtual users the same as concurrent real users?

No. The script's requests, response times, and think times determine how long a virtual user remains active. Use production traffic evidence to model the request mix and arrival rate, then verify the achieved request rate and concurrency in the test.