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

SubjectValue checkedExample
statusHTTP status codestatus == 200
timeResponse time in millisecondstime < 500
sizeBody size in bytessize <= 20000
bodyThe response body as textbody 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 loginscookie sessionid exists
$.pathA 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

OperatorPasses when
== !=The value equals (or does not equal) the expected value
< <= > >=Both sides read as numbers and the comparison holds
contains !containsArrays: 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 endsWithThe text starts or ends with the expected value
matches !matchesA regular expression, written /pattern/flags or bare, does (or does not) match
exists !existsThe header or JSON path is present (or absent); no expected value
isEmpty !isEmptyEmpty string, empty array, empty object, null or missing (or not)
isNumber isString isBoolean isArray isObject isNullThe JSON value has that type
isJsonThe text (for example body) parses as JSON
isTrue isFalseThe value is true (or false); no expected value
md5 sha256 sha512The hash of the value equals the expected digest, given as hex or base64

Expected values

# @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:

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 testPlainwire check
ResCode equal 200status == 200
json.id equal 1$.id == 1
json.items count 3$.items.length == 3
Response time < 500time < 500
Content-Type contains jsonheader 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.