Skip to content

Commit 529e28b

Browse files
vedkribhuvedkribhu
authored
chore: add jsdoc tags to exclude some functions from prerequest script or test script (#965)
1 parent f0da5f5 commit 529e28b

8 files changed

+263
-68
lines changed

‎.jsdoc-config-type-def-sandbox.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@
1616
"excludePattern": "(^|\\/|\\\\)_"
1717
},
1818
"plugins": [
19-
"tsd-jsdoc/dist/plugin"
19+
"tsd-jsdoc/dist/plugin",
20+
"./npm/utils/jsdoc-custom-tags-plugin.js"
2021
],
2122
"templates": {
2223
"cleverLinks": true,

‎lib/sandbox/cookie-jar.js

+20-18
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ const CookieJar = require('@postman/tough-cookie').CookieJar,
6161
},
6262

6363
/**
64-
* Sanitize url object or string to Postman Url instance.
64+
* Sanitize url object or string to Postman URL instance.
6565
*
6666
* @private
6767
* @param {Object|String} url -
@@ -144,7 +144,7 @@ const CookieJar = require('@postman/tough-cookie').CookieJar,
144144
* @todo add CookieJar~getCookie to avoid this
145145
*
146146
* @param {CookieJar} jar - ToughCookie jar instance
147-
* @param {String} url - Url string
147+
* @param {String} url - URL string
148148
* @param {String} name - Cookie name
149149
* @param {Function} callback - Callback function
150150
*/
@@ -173,7 +173,7 @@ const CookieJar = require('@postman/tough-cookie').CookieJar,
173173

174174
class PostmanCookieJar {
175175
/**
176-
* @param {Object} cookieStore -
176+
* @param {Object} cookieStore - Cookie store instance
177177
*/
178178
constructor (cookieStore) {
179179
this.store = cookieStore;
@@ -186,9 +186,9 @@ class PostmanCookieJar {
186186
/**
187187
* Get the cookie value with the given name.
188188
*
189-
* @param {String} url -
190-
* @param {String} name -
191-
* @param {Function} callback -
189+
* @param {String} url - URL string
190+
* @param {String} name - Cookie name
191+
* @param {Function} callback - Callback function
192192
*/
193193
get (url, name, callback) {
194194
url = sanitizeURL(url);
@@ -219,9 +219,11 @@ class PostmanCookieJar {
219219
/**
220220
* Get all the cookies for the given URL.
221221
*
222-
* @param {String} url -
223-
* @param {Object} [options] -
224-
* @param {Function} callback -
222+
* @param {String} url - URL string
223+
* @param {Object} [options] - Options object
224+
* @param {Boolean} [options.http] - Include only HttpOnly cookies
225+
* @param {Boolean} [options.secure] - Include Secure cookies
226+
* @param {Function} callback - Callback function
225227
*/
226228
getAll (url, options, callback) {
227229
url = sanitizeURL(url);
@@ -262,10 +264,10 @@ class PostmanCookieJar {
262264
/**
263265
* Set or update a cookie.
264266
*
265-
* @param {String} url -
266-
* @param {String|Object} name -
267-
* @param {String|Function} [value] -
268-
* @param {Function} [callback] -
267+
* @param {String} url - URL string
268+
* @param {String|Object} name - Cookie name
269+
* @param {String|Function} [value] - Cookie value
270+
* @param {Function} [callback] - Callback function
269271
*/
270272
set (url, name, value, callback) {
271273
url = sanitizeURL(url);
@@ -307,9 +309,9 @@ class PostmanCookieJar {
307309
/**
308310
* Remove single cookie with the given name.
309311
*
310-
* @param {String} url -
311-
* @param {String} name -
312-
* @param {Function} [callback] -
312+
* @param {String} url - URL string
313+
* @param {String} name - Cookie name
314+
* @param {Function} [callback] - Callback function
313315
*/
314316
unset (url, name, callback) {
315317
url = sanitizeURL(url);
@@ -338,8 +340,8 @@ class PostmanCookieJar {
338340
/**
339341
* Remove all the cookies for the given URL.
340342
*
341-
* @param {String} url -
342-
* @param {Function} [callback] -
343+
* @param {String} url - URL string
344+
* @param {Function} [callback] - Callback function
343345
*/
344346
clear (url, callback) {
345347
url = sanitizeURL(url);

‎lib/sandbox/pmapi.js

+3-3
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ function Postman (execution, onRequest, onSkipRequest, onAssertion, cookieStore,
164164
* to the response that was received.
165165
*
166166
* @type {Response}
167-
* @customexclude true
167+
* @excludeFromPrerequestScript
168168
*/
169169
response: execution.response,
170170

@@ -230,8 +230,8 @@ function Postman (execution, onRequest, onSkipRequest, onAssertion, cookieStore,
230230
/**
231231
* Allows one to send request from script asynchronously.
232232
*
233-
* @param {Request|String} req -
234-
* @param {Function} callback -
233+
* @param {Request|String} req - request object or request url
234+
* @param {Function} callback - callback function
235235
*/
236236
sendRequest: function (req, callback) {
237237
var self = this;

‎npm/build-sandbox-types.js

+38-10
Original file line numberDiff line numberDiff line change
@@ -25,21 +25,49 @@ const _ = require('lodash'),
2525
function generateSandboxTypes (node, printer, target) {
2626
var source = '',
2727
excludeResponse = target === 'prerequest',
28-
collectionSDKTypesExtension = '';
28+
collectionSDKTypesExtension = '',
29+
shouldExcludeNode = (node, target) => {
30+
if (!node.jsDoc || node.jsDoc.length === 0) {
31+
return false;
32+
}
2933

30-
node.forEachChild((child) => {
31-
if (excludeResponse && _.get(child, 'name.escapedText') === 'Postman') {
32-
child.members = child.members.filter((m) => {
33-
if (m.name && m.name.escapedText === 'response') {
34+
return node.jsDoc.some((doc) => {
35+
return doc.tags && doc.tags.some((tag) => {
36+
if (tag.tagName.escapedText === `excludeFrom${_.capitalize(target)}Script`) {
37+
return true;
38+
}
39+
});
40+
});
41+
},
42+
removeNodesExcludedFromTarget = (node, target) => {
43+
if (!node || !node.members) {
44+
return node;
45+
}
46+
47+
node.members = node.members.filter((node) => {
48+
if (shouldExcludeNode(node, target)) {
3449
return false;
3550
}
3651

52+
node.forEachChild((child) => {
53+
removeNodesExcludedFromTarget(child, target);
54+
});
55+
3756
return true;
3857
});
39-
}
4058

41-
source += printer.printNode(typescript.EmitHint.Unspecified, child, node);
42-
source += '\n\n';
59+
return node;
60+
},
61+
processChild = (child, target, source, printer, node) => {
62+
removeNodesExcludedFromTarget(child, target);
63+
source += printer.printNode(typescript.EmitHint.Unspecified, child, node);
64+
source += '\n\n';
65+
66+
return source;
67+
};
68+
69+
node.forEachChild((child) => {
70+
source = processChild(child, target, source, printer, node);
4371
});
4472

4573
source += `${templates.postmanExtensionString}\n`;
@@ -148,8 +176,8 @@ module.exports = function (exit) {
148176
});
149177
});
150178

151-
testScriptSource = generateSandboxTypes(node, printer, 'test');
152-
preScriptSource = generateSandboxTypes(node, printer, 'prerequest');
179+
testScriptSource = generateSandboxTypes(_.cloneDeep(node), printer, 'test');
180+
preScriptSource = generateSandboxTypes(_.cloneDeep(node), printer, 'prerequest');
153181

154182
async.each([
155183
{ fileName: `${TARGET_DIR}/prerequest.d.ts`, content: preScriptSource },

‎npm/utils/jsdoc-custom-tags-plugin.js

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
function _onTagged (doclet, tag) {
2+
doclet.description = `${doclet.description}\n@${tag.originalTitle}`;
3+
}
4+
5+
function defineTags (dictionary) {
6+
dictionary.defineTag('excludeFromPrerequestScript', {
7+
onTagged: _onTagged
8+
});
9+
10+
dictionary.defineTag('excludeFromTestScript', {
11+
onTagged: _onTagged
12+
});
13+
}
14+
15+
module.exports = { defineTags };

0 commit comments

Comments
 (0)