🎯 Load Testing with Artillery

Why Artillery?

Artillery is a Node.js load-testing tool. Its signature idea is that a load test should read almost like plain English: you describe who the virtual users are and what they do in YAML, and Artillery turns that description into thousands of coordinated requests. When you need real logic — a random address, a computed token — you drop into ordinary JavaScript.

Think of Artillery as the conductor of an orchestra. Your YAML script is the score; each virtual user is a musician. The conductor decides when new players enter (the phases), what they play (the flows), and afterward hands you a review of the performance (the metrics). Your job is to write a score that sounds like real traffic.

Installing & First Run

Artillery is an npm package. Installing it as a project dev-dependency (rather than globally) keeps the version pinned in package.json, so every teammate and your CI runner use exactly the same one.

# Recommended: install into the project (version pinned for the team + CI)
mkdir load-testing && cd load-testing
npm init -y
npm install --save-dev artillery

# Confirm it works (npx runs the local copy)
npx artillery --version

Before writing a full script, you can fire a one-off smoke test straight from the command line — handy for confirming a target is reachable:

# 10 virtual users, each making 5 requests to the URL
npx artillery quick --count 10 --num 5 https://api.example.com/health

Anatomy of a Test Script

Every Artillery script has two top-level sections. Learn these two words and the rest is detail:

• config — the setup: which server, and how the load ramps over time (the phases).
• scenarios — the behavior: the step-by-step journeys your virtual users perform (the flows).

# basic-test.yml
config:
  target: "https://api.example.com"   # base URL — flow paths are relative to it
  phases:
    - duration: 60                     # for 60 seconds...
      arrivalRate: 5                   # ...5 brand-new virtual users arrive each second
      name: "Warm up"

scenarios:
  - name: "Browse the catalog"
    flow:
      - get:
          url: "/products"            # step 1: list products
      - think: 2                       # step 2: pause 2s, like a human reading
      - get:
          url: "/products/42"         # step 3: view one product

Why think matters: real users pause between clicks. Without think time, your virtual users hammer the server in a tight loop that no real traffic resembles — you'd be measuring an artificial worst case. A second or two of think time between steps produces far more realistic numbers.

Phases: Shaping the Load

A phase controls how many virtual users arrive and when. Two keys do most of the work: arrivalRate (new users per second) and the optional rampTo (climb smoothly to this rate over the phase's duration). Chain phases together to build any traffic shape from the last lesson.

config:
  target: "https://api.example.com"
  phases:
    # 1) Warm up: gently reach the base load so caches and pools fill
    - duration: 30
      arrivalRate: 5
      name: "Warm up"

    # 2) Ramp: climb from 10 to 50 users/sec over two minutes (a load test)
    - duration: 120
      arrivalRate: 10
      rampTo: 50
      name: "Ramp to peak"

    # 3) Sustain: hold peak load to see steady-state behavior
    - duration: 300
      arrivalRate: 50
      name: "Sustained peak"

Want a spike test instead? Sandwich a brief, high-rate phase between two calm ones:

phases:
  - { duration: 60, arrivalRate: 5,  name: "Calm before" }
  - { duration: 30, arrivalRate: 100, name: "Spike!" }
  - { duration: 120, arrivalRate: 5,  name: "Recovery" }

Dynamic Data

If every virtual user requests /products/42, you're really testing your cache, not your database. Realistic load needs variety. Artillery offers three levels of it.

1. Built-in random helpers

Inline template functions generate values on the fly — no setup required.

scenarios:
  - name: "Varied browsing"
    flow:
      # A different product id each time avoids cache-only hits
      - get:
          url: "/products/{{ $randomNumber(1, 500) }}"
      - post:
          url: "/users"
          json:
            username: "user_{{ $randomString(8) }}"
            email: "user_{{ $randomString(8) }}@example.com"

2. Capture a value, reuse it

Real journeys are stateful: list products, grab an id from the response, then act on that id. The capture key pulls a value out of one response into a variable for later steps.

flow:
  - get:
      url: "/products"
      capture:
        - json: "$.products[0].id"   # JSONPath into the response body
          as: "productId"            # save it under this name
  - think: 2
  # Reuse the captured id in the next request
  - get:
      url: "/products/{{ productId }}/reviews"

3. Drive users from a CSV file

To log in as many different real accounts, point Artillery at a CSV. Each virtual user picks up a row and its columns become variables.

config:
  target: "https://api.example.com"
  phases:
    - { duration: 60, arrivalRate: 10 }
  payload:
    path: "users.csv"       # file with a header row
    fields:
      - "username"
      - "password"

scenarios:
  - name: "Log in as many users"
    flow:
      - post:
          url: "/login"
          json:
            username: "{{ username }}"
            password: "{{ password }}"

Thresholds & SLAs

A test that only prints numbers is a report. A test that fails the build when numbers cross a line is a guardrail. This is where load testing earns its place in CI: encode your Service Level Agreement as thresholds, and Artillery exits non-zero the moment reality misses the target.

config:
  target: "https://api.example.com"
  phases:
    - { duration: 120, arrivalRate: 20, name: "Load" }
  ensure:
    thresholds:
      # 95% of requests must complete under 300 ms
      - http.response_time.p95: 300
      # 99% of requests must complete under 800 ms
      - http.response_time.p99: 800
    # And the overall error rate must stay tiny
    conditions:
      - expression: "http.request_rate > 0"

Pair thresholds with the expect plugin to assert on correctness under load too — a fast 500 error is still a failure:

config:
  plugins:
    expect: {}
scenarios:
  - name: "Validated request"
    flow:
      - get:
          url: "/users/1"
          expect:
            - statusCode: 200
            - contentType: "application/json"

Running & Reading Results

Run a script, and optionally save a machine-readable report you can turn into HTML or feed to a dashboard.

# Run the test
npx artillery run ecommerce-test.yml

# Run and save a JSON report, then render an HTML view of it
npx artillery run --output report.json ecommerce-test.yml
npx artillery report report.json

Artillery streams a summary as it runs. The numbers to read first are exactly the four from the previous lesson:

http.requests ............................ 12000     ← total requests sent
http.request_rate ........................ 198/sec   ← throughput (RPS)
http.response_time:
  min .................................... 12
  median (p50) ........................... 47
  p95 .................................... 260
  p99 .................................... 910        ← the tail — watch this
http.codes.200 ........................... 11940
http.codes.500 ........................... 60         ← 0.5% error rate
vusers.failed ............................ 60

How to read it: throughput of ~198 RPS is your capacity at this load. The median (47 ms) says the typical user is happy. The p99 of 910 ms is the real story — one in a hundred requests is nearly a second, and 60 requests returned 500s. If your SLA said "p99 under 800 ms," this run fails, and the 500s point at something breaking under pressure (an exhausted connection pool? a slow query surfacing under concurrency?). That failing number is your cue for the next lesson: optimization.

Practice & Quiz

config:
  target: "https://api.example.com"
  phases:
    - { duration: 30, arrivalRate: 5,  name: "Warm up" }
    - { duration: 120, arrivalRate: 20, name: "Load" }
  ensure:
    thresholds:
      - http.response_time.p95: 400

scenarios:
  - name: "Browse and add to cart"
    flow:
      - get:
          url: "/products"
          capture:
            - json: "$.products[0].id"
              as: "productId"
      - think: 2
      - post:
          url: "/cart"
          json:
            productId: "{{ productId }}"
            quantity: 1

phases:
  - { duration: 60,  arrivalRate: 10,  name: "Calm" }
  - { duration: 20,  arrivalRate: 120, name: "Spike" }
  - { duration: 120, arrivalRate: 10,  name: "Recovery" }

Best Practices & Pitfalls

✅ Do

• Start with a warm-up phase so cold-start costs don't pollute your metrics
• Use dynamic data (random values, captures, CSVs) so you test more than the cache
• Include realistic think time between steps
• Encode your SLA as thresholds so regressions fail the build
• Keep scripts in the repo and run them in CI against a staging environment

❌ Don't

• Load-test production without explicit permission — you can cause a real outage
• Put real credentials or payment details in test files
• Hit the same URL every time and mistake cache hits for real performance
• Trust results when your own laptop (the load generator) is maxed out

Summary

📚 Additional Resources

• Artillery — Official documentation
• Artillery — Test script reference
• k6 — Docs (the JavaScript alternative)
• MDN — Web Performance guide

🚀 What's Next?

You can now generate load and read the report that comes back. When that report shows a slow tail or rising errors, what do you actually do about it? Next: Performance Optimization — measuring first, finding the real bottleneck, and fixing it with caching, indexes, pagination, and non-blocking code.