diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..b82bb59d --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "pactum" + ] +} \ No newline at end of file diff --git a/docs/api/assertions/expectJson.md b/docs/api/assertions/expectJson.md index 948d8735..68ee4740 100644 --- a/docs/api/assertions/expectJson.md +++ b/docs/api/assertions/expectJson.md @@ -12,17 +12,20 @@ Performs deep equal of JSON objects. ```js expectJson(json) -expectJson(path, json) +expectJson(template-name) +expectJson(file-path) +expectJson(file-name) +expectJson(json-path, json) ``` ## Usage ### ✅ Correct Usage -```js +```js await spec() .get('api/health') - .expectJson({ + .expectJson({ message: 'OK' }); ``` @@ -33,7 +36,15 @@ await spec() Response json body. -#### > path (string) +#### > template-name (string) + +name of the data template to use. + +#### > file-name (string) + +name of the json file to use. + +#### > json-path (string) Json path. See [json-query](https://www.npmjs.com/package/json-query) for more usage details. @@ -70,4 +81,55 @@ await spec() .get('https://reqres.in/api/users/1') .expectJson('data.first_name', 'George') .expectJson('data.last_name', 'Bluth'); -``` \ No newline at end of file +``` + +### Using data template + +```js +const { spec, stash } = require('pactum'); + +stash.addDataTemplate({ + 'FIRST_USER': { + "data": { + "id": 1, + "email": "george.bluth@reqres.in", + "first_name": "George", + "last_name": "Bluth", + "avatar": "https://reqres.in/img/faces/1-image.jpg" + }, + "support": { + "url": "https://reqres.in/#support-heading", + "text": "To keep ReqRes free, contributions towards server costs are appreciated!" + } + } +}); + +await spec() + .get('https://reqres.in/api/users/1') + .expectJson('FIRST_USER'); +``` + +### Using file path + +```js +const { spec } = require('pactum'); + +await spec() + .get('https://reqres.in/api/users/1') + .expectJson('./data/user.json'); +``` + +#### Using file name + +```js +const { spec } = require('pactum'); + +await spec() + .get('https://reqres.in/api/users/1') + .expectJson('user.json') // searches for the file inside the data folder + .expectStatus(201); +``` + +## See Also + +- [setDataDirectory](/api/settings/setDataDirectory) \ No newline at end of file diff --git a/docs/api/assertions/expectJsonLike.md b/docs/api/assertions/expectJsonLike.md index 1df7463a..eb4a17f6 100644 --- a/docs/api/assertions/expectJsonLike.md +++ b/docs/api/assertions/expectJsonLike.md @@ -18,6 +18,9 @@ Performs partial equal of JSON objects. ```js expectJsonLike(json) +expectJson(template-name) +expectJson(file-path) +expectJson(file-name) expectJsonLike(path, json) ``` @@ -25,10 +28,10 @@ expectJsonLike(path, json) ### ✅ Correct Usage -```js +```js await spec() .get('api/health') - .expectJsonLike({ + .expectJsonLike({ message: 'OK' }); ``` @@ -61,6 +64,49 @@ await spec() }); ``` +### Using data template + +```js +const { spec, stash } = require('pactum'); + +stash.addDataTemplate({ + 'FIRST_USER': { + "data": { + "id": 1, + "email": "george.bluth@reqres.in", + "first_name": "George", + "last_name": "Bluth", + "avatar": "https://reqres.in/img/faces/1-image.jpg" + } + } +}); + +await spec() + .get('https://reqres.in/api/users/1') + .expectJsonLike('FIRST_USER'); +``` + +### Using file path + +```js +const { spec } = require('pactum'); + +await spec() + .get('https://reqres.in/api/users/1') + .expectJsonLike('./data/user.json'); +``` + +#### Using file name + +```js +const { spec } = require('pactum'); + +await spec() + .post('https://reqres.in/api/users') + .expectJsonLike('user.json') // searches for the file inside the data folder + .expectStatus(201); +``` + ### Regular Expressions ```js @@ -79,7 +125,7 @@ await spec() ### Assert Expressions -Assert Expressions helps to run custom JavaScript code on a JSON that performs user defined assertions. +Assert Expressions helps to run custom JavaScript code on a JSON that performs user defined assertions. - Expression should contain `$V` to represent current value. - Expression should be a valid JavaScript code. @@ -121,4 +167,5 @@ await spec() ## See Also -- [Assert Handlers](/api/handlers/addAssertHandler) \ No newline at end of file +- [Assert Handlers](/api/handlers/addAssertHandler) +- [setDataDirectory](/api/settings/setDataDirectory) \ No newline at end of file diff --git a/docs/api/assertions/expectJsonMatch.md b/docs/api/assertions/expectJsonMatch.md index aba9878f..bbdeede1 100644 --- a/docs/api/assertions/expectJsonMatch.md +++ b/docs/api/assertions/expectJsonMatch.md @@ -14,6 +14,9 @@ Assert a JSON using a set of matchers. ```js expectJsonMatch(json) +expectJson(template-name) +expectJson(file-path) +expectJson(file-name) expectJsonMatch(path, json) ``` @@ -21,10 +24,10 @@ expectJsonMatch(path, json) #### ✅ Correct Usage -```js +```js await spec() .get('api/users/1') - .expectJsonMatch({ + .expectJsonMatch({ id: like(1) }); ``` @@ -41,7 +44,7 @@ Json path. See [json-query](https://www.npmjs.com/package/json-query) for more u ## Examples -### Partial deep equal +### Partial deep equal ```js const { spec } = require('pactum'); @@ -65,4 +68,9 @@ const { spec } = require('pactum'); await spec() .get('https://reqres.in/api/users/1') .expectJsonMatch('data.first_name', like('George')); -``` \ No newline at end of file +``` + +## See Also + +- [Matching](/guides/matching) +- [setDataDirectory](/api/settings/setDataDirectory) \ No newline at end of file diff --git a/docs/api/assertions/expectJsonMatchStrict.md b/docs/api/assertions/expectJsonMatchStrict.md index 238e820b..e9c8f551 100644 --- a/docs/api/assertions/expectJsonMatchStrict.md +++ b/docs/api/assertions/expectJsonMatchStrict.md @@ -14,6 +14,9 @@ Assert a JSON using a set of strict matchers. ```js expectJsonMatchStrict(json) +expectJson(template-name) +expectJson(file-path) +expectJson(file-name) expectJsonMatchStrict(path, json) ``` @@ -21,10 +24,10 @@ expectJsonMatchStrict(path, json) #### ✅ Correct Usage -```js +```js await spec() .get('api/users/1') - .expectJsonMatchStrict({ + .expectJsonMatchStrict({ id: like(1) }); ``` @@ -41,7 +44,7 @@ Json path. See [json-query](https://www.npmjs.com/package/json-query) for more u ## Examples -### Partial deep equal +### Partial deep equal ```js const { spec } = require('pactum'); @@ -65,4 +68,9 @@ const { spec } = require('pactum'); await spec() .get('https://reqres.in/api/users/1') .expectJsonMatchStrict('data.first_name', like('George')); -``` \ No newline at end of file +``` + +## See Also + +- [Matching](/guides/matching) +- [setDataDirectory](/api/settings/setDataDirectory) \ No newline at end of file diff --git a/docs/api/assertions/expectJsonSchema.md b/docs/api/assertions/expectJsonSchema.md index dadbda76..de67128d 100644 --- a/docs/api/assertions/expectJsonSchema.md +++ b/docs/api/assertions/expectJsonSchema.md @@ -16,6 +16,9 @@ Assert based on JSON schema. ```js expectJsonSchema(schema) +expectJson(template-name) +expectJson(file-path) +expectJson(file-name) expectJsonSchema(path, schema) ``` @@ -23,7 +26,7 @@ expectJsonSchema(path, schema) ### ✅ Correct Usage -```js +```js await spec() .get('api/users/1') .expectJsonSchema({ @@ -66,4 +69,8 @@ await spec() .expectJsonMatch('data', { "type": "object" }); -``` \ No newline at end of file +``` + +## See Also + +- [setDataDirectory](/api/settings/setDataDirectory) \ No newline at end of file diff --git a/docs/api/requests/spec.md b/docs/api/requests/spec.md index 815378e5..9f009054 100644 --- a/docs/api/requests/spec.md +++ b/docs/api/requests/spec.md @@ -21,14 +21,14 @@ spec(handler-name, handler-options) ### ✅ Correct Usage ```js -// always use 'await' statement +// always use 'await' statement await spec() .get('/api/users/1') .expectStatus(200); ``` ```js -// invoke the 'toss' method at the end to return a promise +// invoke the 'toss' method at the end to return a promise spec() .get('/api/users/1') .expectStatus(200) @@ -63,8 +63,8 @@ spec().get('url').expectStatus(200); ``` ```js -// cannot make multiple requests with the same spec object. -// Instead use multiple 'spec()' methods. +// cannot make multiple requests with the same spec object. +// Instead use multiple 'spec()' methods. await spec() .get('/api/users/1') .expectStatus(200) @@ -79,15 +79,22 @@ await spec(); ## Arguments -#### > handler-name (string) +#### > handler-name *(string)* -Name of the spec handler to use. +Name of the spec handler to use. > Handlers should be defined before the usage. Else it will throw an error. -#### > handler-options (any) +#### > 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. -Handler options could be anything. With the help of this options, we can make the spec handlers dynamic. ## Yields @@ -135,6 +142,42 @@ 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 - [API Testing](/guides/api-testing) \ No newline at end of file diff --git a/docs/api/requests/withJson.md b/docs/api/requests/withJson.md index 3587438b..46d1c043 100644 --- a/docs/api/requests/withJson.md +++ b/docs/api/requests/withJson.md @@ -13,6 +13,7 @@ Request body as json payload. ```js withJson(payload) +withJson(template-name) withJson(file_path) withJson(file_name) ``` @@ -43,7 +44,7 @@ relative path to the json file. #### > file_name (string) -name of the file. This will looks for a file inside the `./data` folder and any folders nested within it. +name of the file. This will looks for a file inside the `./data` folder and any folders nested within it. ::: tip Tip We can customize the data folder path using [setDataDirectory](/api/settings/setDataDirectory). @@ -51,7 +52,7 @@ We can customize the data folder path using [setDataDirectory](/api/settings/set ## Examples -#### Payload +#### Payload ```js const { spec } = require('pactum'); @@ -65,7 +66,26 @@ await spec() .expectStatus(201); ``` -#### File Path +#### Data Template + +```js +const { spec, stash } = require('pactum'); + +stash.addDataTemplate({ + 'USER_PAYLOAD': { + "name": "morpheus", + "job": "leader" + } +}); + + +await spec() + .post('https://reqres.in/api/users') + .withJson('USER_PAYLOAD') + .expectStatus(201); +``` + +#### File Path ```js const { spec } = require('pactum'); @@ -76,7 +96,7 @@ await spec() .expectStatus(201); ``` -#### File Name +#### File Name ```js const { spec } = require('pactum');