Tests & Assertions
Write tests in the Post-Response script to check every response automatically. Results appear in the response's Tests tab.
test('Status is 200', () => {
assert(dotfetch.response.status === 200, `Expected 200, got ${dotfetch.response.status}`);
});
test('Returns the requested user', () => {
const user = dotfetch.response.json();
assert(user.id === 42, `Expected id 42, got ${user.id}`);
assert(typeof user.email === 'string', 'email is missing');
});The Tests tab:
✓ 2 passed 2 total tests
✓ Status is 200 0ms
✓ Returns the requested user 1mstest(name, fn)
Runs fn and records a pass or a fail under name. Available in Post-Response scripts only.
- If
fnfinishes without throwing, the test passes. - If
fnthrows, through a failedassert()or any other error, the test fails and the message is shown under it. - A failing test doesn't stop the script. The remaining tests still run, so you see every problem at once.
test('Has a body', () => {
assert(dotfetch.response.body.length > 0, 'Body is empty');
});
test('Is JSON', () => {
dotfetch.response.json(); // throws "Response body is not valid JSON" if it isn't
});assert(condition, message)
Throws if condition is falsy. message is optional; without it, you get Assertion failed.
assert(user.active); // fails with: Assertion failed
assert(user.active, 'User should be active'); // fails with: User should be activeWrite messages that say what was expected and what actually came back. They're what you'll read in the Tests tab:
assert(items.length === 3, `Expected 3 items, got ${items.length}`);assert() also works outside test() and in Pre-Request scripts. There, a failure stops the whole script:
// Pre-Request: refuse to send without a token
assert(dotfetch.env.get('ACCESS_TOKEN'), 'Log in first: ACCESS_TOKEN is not set');⚠️ Pre-request script failed (line 2): Log in first: ACCESS_TOKEN is not set
The request isn't sent. See When a script fails.
Common checks
const res = dotfetch.response;
test('Status is 2xx', () => {
assert(res.status >= 200 && res.status < 300, `Got ${res.status}`);
});
test('Responds within 500 ms', () => {
assert(res.time < 500, `Took ${res.time} ms`);
});
test('Returns JSON', () => {
const type = res.headers['content-type'] ?? '';
assert(type.includes('application/json'), `Content-Type was "${type}"`);
});
test('Every item has an id and a price', () => {
const { items } = res.json();
assert(Array.isArray(items), 'items is not an array');
items.forEach((item, i) => {
assert(item.id, `items[${i}] has no id`);
assert(typeof item.price === 'number', `items[${i}].price is not a number`);
});
});
test('Error responses explain themselves', () => {
if (res.status >= 400) {
assert(res.json().message, 'Error response has no message');
}
});Test and save in one script
Tests and dotfetch.env.set() can live together. Save a value only when the tests that guard it passed:
const body = dotfetch.response.json();
let ok = true;
test('Login succeeded', () => {
try {
assert(dotfetch.response.status === 200, `Status ${dotfetch.response.status}`);
assert(body.token, 'No token in response');
} catch (e) {
ok = false;
throw e; // still report the failure
}
});
if (ok) {
dotfetch.env.set('ACCESS_TOKEN', body.token);
}No async tests
Scripts are synchronous. A test with an async callback is reported as failed with:
Async tests are not supported — remove async/await from the test() callback
Everything a test needs, the response included, is already available, so there's nothing to await.
// ✕ fails
test('Status', async () => { assert(dotfetch.response.status === 200); });
// ✓ works
test('Status', () => { assert(dotfetch.response.status === 200); });Reading the results
| Badge on the Tests tab | Meaning |
|---|---|
✓ 3 (green) | All 3 tests passed |
✕ 1 (red) | 1 test failed, or the script itself threw an error |
| none | The script ran no tests |
If the script throws outside a test(), the Tests tab shows a ⚠️ Post-Response Script Error (Line N) card above the tests that had already finished.