API testing in VS Code with .http files
Plainwire 0.2.0 adds response checks to plain .http files and a Run all collection runner. A check is a comment line, # @assert status == 200, placed above the request it tests. It runs after every send, and Run all sends a whole file or workspace in order and gives you a pass/fail report. Because the checks are comments, the same file still works unchanged in REST Client, which simply ignores them.
Everything on this page needs Plainwire 0.2.0 or newer. Install the .vsix from the latest GitHub release (see install steps).
A complete example
The grammar is # @assert <subject> <operator> [expected]. Put as many as you like between the ### line and the request line. This file logs in, creates an item with the token, then reads the item back and checks it:
# api/items.http @baseUrl = http://localhost:3000 ### Log in # @name login # @assert status == 200 # @assert $.token isString # @assert time < 1000 POST {{baseUrl}}/auth/login Content-Type: application/json { "email": "ada@example.com", "password": "{{password}}" } ### Create an item # @name createItem # @assert status == 201 # @assert header content-type contains json # @assert $.id exists # @assert $.name == "Desk lamp" # @assert $.tags contains "office" POST {{baseUrl}}/items Authorization: Bearer {{login.response.body.$.token}} Content-Type: application/json { "name": "Desk lamp", "price": 39.5, "tags": ["office", "lighting"] } ### Read it back # @assert status == 200 # @assert $.id == {{createItem.response.body.$.id}} # @assert $.price > 0 # @assert $.tags.length == 2 # @assert $.createdAt matches /^\d{4}-\d{2}-\d{2}T/ GET {{baseUrl}}/items/{{createItem.response.body.$.id}} Authorization: Bearer {{login.response.body.$.token}}
{{password}} comes from http-client.private.env.json; see environments. Click Run all 3 requests (13 checks) above the first line and you get one report for the whole flow.
What you can check
| Subject | Value checked | Example |
|---|---|---|
status | HTTP status code | status == 200 |
time | Response time in milliseconds | time < 500 |
size | Body size in bytes | size <= 20000 |
body | The response body as text | body contains "ok" |
header <name> | A response header; the name is case-insensitive and repeated headers are joined with ", " | header cache-control contains no-store |
cookie <name> | A cookie this response sets with Set-Cookie (a Set-Cookie that deletes it counts as not set). See cookies and session logins | cookie sessionid exists |
$.path | A JSONPath into the JSON body: $.id, $.data[0].name, $.items[-1] (last element), $['key with space'], $.items.length. body.$.id also works. | $.data[0].name == "Ada" |
events… | For a server-sent events response: events.length, events[0].event, events[-1].id, and events[0].data (JSON data is parsed, so events[0].data.text works) | events[-1].data == "[DONE]" |
Operators
| Operator | Passes when |
|---|---|
== != | The value equals (or does not equal) the expected value |
< <= > >= | Both sides read as numbers and the comparison holds |
contains !contains | Arrays: the expected value is (or is not) an element. Text: it is (or is not) a substring. not contains is the same as !contains. |
startsWith endsWith | The text starts or ends with the expected value |
matches !matches | A regular expression, written /pattern/flags or bare, does (or does not) match |
exists !exists | The header or JSON path is present (or absent); no expected value |
isEmpty !isEmpty | Empty string, empty array, empty object, null or missing (or not) |
isNumber isString isBoolean isArray isObject isNull | The JSON value has that type |
isJson | The text (for example body) parses as JSON |
isTrue isFalse | The value is true (or false); no expected value |
md5 sha256 sha512 | The hash of the value equals the expected digest, given as hex or base64 |
Expected values
- JSON first, then text. The expected value is read as JSON if it parses, so
200,true,null,"quoted text"and["x","y"]are typed values. Anything else, such asjsonorDesk lamp, is plain text. - Loose comparison.
"200" == 200passes, so an id that one API returns as a string and another as a number does not break a check. - Variables work.
{{variables}}are filled in before the check runs, including environment values and chained responses:# @assert $.id == {{userId}}.
# @assert $.roles contains "admin" (array membership) # @assert body !contains "stack trace" (substring) # @assert $.email matches /@example\.com$/i # @assert $['display name'] !isEmpty # @assert $.deletedAt isNull # @assert $.items[-1].id == {{lastId}}
Run all
There are four ways to start a run:
- The Run all N requests (M checks) CodeLens at the top of any
.httpfile. - The run button in the editor title bar while a
.httpfile is open. - Right-click a file or a folder in the Explorer and choose Run All Requests in File.
- Run All Requests in Workspace in the Plainwire sidebar.
Requests run in file order, so chaining with # @name login and {{login.response.body.$.token}} works across the run. A request passes when all of its checks pass. A request with no checks passes on any status below 400; to expect an error, say so with # @assert status == 404. Add # @skip above a request to leave it out of runs (you can still send it by hand).
### Wipe the test database (never in a run) # @skip POST {{baseUrl}}/admin/reset
The report lists every request with its status, time and checks. A failed request shows which check failed and the actual value it got, for example expected 201, got 400. Re-run failed sends only the failures again (plus any named request they read values from, so chained tokens are fresh), and Copy report (Markdown) copies a table you can paste into a pull request or issue.
Checks in the request editor
You do not have to type the comment lines. The request editor has a Tests tab where you add and edit checks, with quick-add chips for common ones such as a status check. Plainwire writes them back to the file as # @assert lines. After a send, the response bar shows ✓ 3 checks passed or ✗ 1 of 3 checks failed, and the response’s Tests tab lists each check with its result.
Coming from Thunder Client tests
When you import a Thunder Client collection, its tests are converted to # @assert lines: status code, response time, body contains, JSON query equal, count and type, Content-Type and other header checks. Any test that cannot be converted is listed as a warning after the import, so nothing disappears silently.
| Thunder Client test | Plainwire check |
|---|---|
| ResCode equal 200 | status == 200 |
| json.id equal 1 | $.id == 1 |
| json.items count 3 | $.items.length == 3 |
| Response time < 500 | time < 500 |
| Content-Type contains json | header content-type contains json |
Runs are not counted or capped, so a collection you used to ration can run on every change. For the wider switch, see the Thunder Client alternative guide.
Postman test snippets
The Postman importer recognises the common one-line test snippets and converts them the same way:
var jsonData = pm.response.json(); (recognised, so jsonData.x maps to $.x) pm.response.to.have.status(200) → status == 200 pm.expect(pm.response.responseTime).to.be.below(500) → time < 500 pm.response.to.have.header("X-Request-Id") → header X-Request-Id exists pm.expect(jsonData.name).to.eql("Ada") → $.name == "Ada" pm.expect(pm.response.text()).to.include("ok") → body contains "ok" pm.expect(jsonData.items).to.have.lengthOf(3) → $.items.length == 3
A test script made only of such snippets becomes # @assert lines. Since 0.13, any other test script (one that sets variables, or has an if, a loop or other free-form JavaScript) is kept whole as a > {% %} response handler and runs with a Postman-compatible pm API, so its pm.test results appear next to your other checks. Pre-request scripts are kept as < {% %} blocks. See Postman scripts for what the pm API covers.
httpYac ?? lines
If your files were written for httpYac, their ?? test lines run in Plainwire without changes, in the editor, in Run all and in the CLI:
GET {{base}}/users/1
?? status == 200
?? header content-type includes json
?? body $.id exists
?? duration < 500
?? js response.parsedBody.name == "Ada"
Supported subjects: status, duration, header <name>, body and body $.path, and js with simple paths only (response.parsedBody.…, response.body.…, response.statusCode, response.headers['x']). Plainwire does not evaluate other ?? js expressions, so they, and ?? xpath, are reported as a failed check that says “unsupported httpYac assertion”, never as a silent pass.
Need more than one line? Since 0.13, a > {% %} response handler can run checks with loops and conditions through client.test, and save values for later requests with client.global.set; a < {% %} pre-request script can compute a signature before sending. See pre-request scripts and tests in .http files. httpYac’s own {{ }} script blocks are not run.
The same checks run outside VS Code with the free plainwire command-line runner and GitHub Action, which exit non-zero on failure and write JUnit XML: see Run .http files in CI.
Questions
Is it free?
Yes. Plainwire is MIT-licensed open source with no account and no limit on requests, checks or runs.
Does it work in Cursor and VSCodium?
Plainwire is a standard VS Code extension built for VS Code 1.85 or newer. Cursor, Windsurf and VSCodium install the same .vsix with Extensions: Install from VSIX….
Will the checks break my files in REST Client or JetBrains?
No. Every # @assert line is a comment, so other clients send the request as before and skip the line. Only Plainwire evaluates it.
Can I check a response without running the whole file?
Yes. Checks run on every send, including a single Send Request from the CodeLens or the editor.
The rest of the format is on the .http syntax cheat sheet.