Skip to main content

Scripting ›Tests & Assertions

Изменить на GitHub

Эта документация доступна на английском языке.

Tests & Assertions

Write tests in the Post-Response script to check every response automatically. Results appear in the response's Tests tab.

JS
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:

CODE
✓ 2 passed                                   2 total tests
✓ Status is 200                                       0ms
✓ Returns the requested user                          1ms

test(name, fn)

Runs fn and records a pass or a fail under name. Available in Post-Response scripts only.

  • If fn finishes without throwing, the test passes.
  • If fn throws, through a failed assert() 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.
JS
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.

JS
assert(user.active);                          // fails with: Assertion failed
assert(user.active, 'User should be active'); // fails with: User should be active

Write messages that say what was expected and what actually came back. They're what you'll read in the Tests tab:

JS
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:

JS
// 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

JS
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:

JS
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.

JS
// ✕ fails
test('Status', async () => { assert(dotfetch.response.status === 200); });

// ✓ works
test('Status', () => { assert(dotfetch.response.status === 200); });

Reading the results

Badge on the Tests tabMeaning
✓ 3 (green)All 3 tests passed
✕ 1 (red)1 test failed, or the script itself threw an error
noneThe 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.

Tests & Assertions · DotFetch Docs | dotsuite