Skip to content
On this page

Empower Your Test Results with AI-Powered Insights ->

spec

Builds a single request and respective expectations. In general, it represents a single API call or a single test case. It forms the base for other types of testing like e2e, flow and fuzz.

Syntax

js
spec()
spec(handler-name)
spec(handler-name, handler-options)

Usage

โœ… Correct Usage

js
// always use 'await' statement
await spec()
  .get('/api/users/1')
  .expectStatus(200);
js
// invoke the 'toss' method at the end to return a promise
spec()
  .get('/api/users/1')
  .expectStatus(200)
  .toss().then().catch();
js
// use without chaining method calls
const sp = spec();
sp.get('/api/users/1');
sp.expectStatus(200);
await sp.toss(); // runs the test
js
// using handler
await spec('get user')
  .expectJson('data.first_name', 'George');
js
// using handler and custom handler-options
await spec('get user', 2)
  .expectJson('data.first_name', 'Janet');

โ— Incorrect Usage

js
// will not make an api call as there is no 'await' statement or 'toss' method
spec().get('url').expectStatus(200);
js
// cannot make multiple requests with the same spec object.
// Instead use multiple 'spec()' methods.
await spec()
  .get('/api/users/1')
  .expectStatus(200)
  .post('/api/users/2')
  .expectStatus(201);
js
// empty spec details will fail
await spec();

Arguments

> handler-name (string)

Name of the spec handler to use.

Handlers should be defined before the usage. Else it will throw an error.

> handler-data? (any)

Handler data could be anything. With the help of this data, we can make the spec handlers dynamic.

> handler-options? (object)

Handler options to control the behavior of the spec handler.

  • memo (any) - Memoize the spec handler. If the spec handler is already memoized, it will not run the spec handler. The value of memo can be anything. Based on this value, it will decide if to run the spec handler or not.

Yields

Returns an object of spec which contains all the methods for making a request and validating the response.

Examples

Normal

js
const { spec } = require('pactum');

await spec()
  .get('https://reqres.in/api/users/1')
  .expectStatus(200);

Multiple Request Calls

js
const { spec } = require('pactum');

await spec()
  .get('https://reqres.in/api/users/1')
  .expectStatus(200);

await spec()
  .get('https://reqres.in/api/users/2')
  .expectStatus(200);

Using Handlers

js
const { spec, handler } = require('pactum');

handler.addSpecHandler('get user', (ctx) => {
  const { spec, data } = ctx;
  spec.get('https://reqres.in/api/users/{id}');
  spec.withPathParams('id', data || 1)
  spec.expectStatus(200);
});

await spec('get user').expectJson('data.first_name', 'George');
await spec('get user', 2).expectJson('data.first_name', 'Janet');

Using Handlers Memo

memo as boolean

js
const { spec, handler } = require('pactum');

handler.addSpecHandler('get settings', (ctx) => {
  const { spec } = ctx;
  spec.get('https://example.com/settings');
  spec.expectStatus(200);
  spec.stores('SETTINGS', '.');
});

await spec('get settings', null, { memo: true }); // this will be executed
await spec('get settings', null, { memo: true }); // this won't be executed

memo as string

js
const { spec, handler } = require('pactum');

handler.addSpecHandler('get settings', (ctx) => {
  const { spec, data } = ctx;
  spec.get(`https://example.com/settings/${data}`);
  spec.expectStatus(200);
  spec.stores(`SETTINGS:${data}`, '.');
});

await spec('get settings', 'user', { memo: 'user' }); // this will be executed
await spec('get settings', 'org', { memo: 'org' }); // this will be executed
await spec('get settings', 'user', { memo: 'user' }); // this won't be executed
await spec('get settings', 'org', { memo: 'org' }); // this won't be executed

See Also

Released under the MIT License.