Custom Load-Testing Tool built on wrk Lua Scripting

Project roadmap

1. 01

   Set up wrk and a target server

   ~1.5h

   Install wrk (from your package manager or by building it from source). Write a small target server in any language with a few endpoints (GET /products, GET /products/:id, POST /cart, POST /login) that have different response times and occasionally return errors, so there's something interesting to measure. Run a first test with wrk -t4 -c50 -d30s and note the results. Done when: wrk runs against your server and prints its default summary.

2. 02

   Write a basic request script

   ~1h

   Create scripts/basic.lua that defines request() and returns wrk.format("GET", path) for a fixed path. Run it with wrk -s scripts/basic.lua. Read the wrk scripting documentation and write down in the README when each hook (setup, init, request, response, done) runs and in which Lua state, since each wrk thread has its own separate Lua state. Done when: the script runs, and the README explains the hooks and threads.

3. 03

   Model a weighted traffic mix

   ~2h

   Describe the traffic mix in a Lua table: each entry has a method, a path template (such as /products/{id}), an optional body and a weight (for example 60% product views, 25% product lists, 15% add to cart). In request(), pick an entry at random according to the weights, fill in random ids, and build the request with headers and a JSON body. Seed the random generator differently in each thread. Done when: the server's logs show the requested mix of endpoints.

4. 04

   Handle authentication

   ~1.5h

   Some endpoints need a token. Log in before the test starts, for example with a separate request in init() or by passing a token through wrk's arguments, and add Authorization: Bearer <token> to protected requests. If responses start returning 401 because the token expired, log in again. Done when: protected endpoints return 200 during the whole test.

5. 05

   Collect per-endpoint metrics

   ~2.5h

   wrk doesn't know which endpoint each response belongs to, so record it in request() and read it back in response(status, headers, body). Count requests and errors (non-2xx) per endpoint, and record latencies in a histogram per endpoint. Use setup(thread) to keep a reference to each thread, so done() can read and merge every thread's tables at the end. Done when: the counts per endpoint add up to wrk's total number of requests.

6. 06

   Print a percentile report

   ~2h

   In done(), print a table per endpoint with the request count, error rate and latency at the 50th, 90th, 99th and 99.9th percentiles, plus wrk's overall summary. Write the same data to a JSON file. Explain in the README why the 99th percentile matters more than the average for users. Done when: the report shows clearly different percentiles for the slow and fast endpoints.

7. 07

   Compare runs to catch regressions

   ~2h

   Write a small script, in Lua or another language, that compares two JSON reports and flags endpoints whose 99th percentile latency got more than 20% worse or whose error rate increased. Wrap everything in a run.sh with named scenarios (smoke, normal, peak) that set threads, connections and duration. Done when: making one endpoint slower on purpose is flagged when comparing with the previous report.

Resources

• Docswrk on GitHub
• Docswrk scripting documentation (SCRIPTING)
• ArticleLearn Lua in Y minutes
• VideoHow NOT to measure latency (Gil Tene)