feat(pmapi): add support to get path of current request in sandbox sc…

…ript

CHANGELOG.yaml

@@ -1,3 +1,7 @@
+unreleased:
+    new features:
+     - GH-950 Added support for pm.execution.location
+
 4.3.0:
   date: 2023-11-02
   new features:

lib/sandbox/execution-location.js

@@ -0,0 +1,17 @@
+class ExecutionLocation extends Array {
+    /**
+     *
+     * @param {string} current - Current item name, current item is the item whose script is being executed
+     * @param  {string} rest - Arguments to pass to Array constructor
+     */
+    constructor (current, ...rest) {
+        super(...rest);
+        this._current = current;
+    }
+
+    get current () {
+        return this._current;
+    }
+}
+
+module.exports = ExecutionLocation;

lib/sandbox/pmapi.js

@@ -6,6 +6,7 @@ const _ = require('lodash'),
     PostmanResponse = sdk.Response,
     PostmanCookieList = sdk.CookieList,
     chai = require('chai'),
+    ExecutionLocation = require('./execution-location'),
 
     /**
      * Use this function to assign readonly properties to an object
@@ -269,7 +270,26 @@ function Postman (execution, onRequest, onSkipRequest, onAssertion, cookieStore,
              * @excludeFromTestScript
              * @instance
              */
-            skipRequest: onSkipRequest
+            skipRequest: onSkipRequest,
+
+            /**
+             * @interface ExecutionLocationInterface
+             * @extends Array<string>
+             */
+            /**
+             * The element name whose script is currently being executed.
+             *
+             * @name ExecutionLocationInterface#current
+             * @type {string}
+             */
+            /**
+             * The path of the current request.
+             *
+             * @type {ExecutionLocationInterface} - current execution path
+             * @instance
+             */
+            location: new ExecutionLocation(execution.legacy._eventItemName,
+                ...(execution.legacy._itemPath || []))
         }
     }, options.disabledAPIs);
 

test/unit/sandbox-libraries/pm.test.js

@@ -1087,5 +1087,39 @@ describe('sandbox library - pm api', function () {
                 });
             });
         });
+
+        describe('.location', function () {
+            it('should return the correct path of the request', function (done) {
+                context.execute({
+                    script: `
+                        var assert = require('assert');
+                        assert.deepEqual(Array.from(pm.execution.location), ['C1', 'R1']);
+                    ` }, {
+                    legacy: {
+                        _itemName: 'request-name',
+                        _itemId: 'request-id',
+                        _itemPath: ['C1', 'R1'],
+                        _eventItemName: 'R1'
+                    }
+                }, done);
+            });
+
+            describe('.current ', function () {
+                it('should return the correct current item', function (done) {
+                    context.execute({
+                        script: `
+                            var assert = require('assert');
+                            assert.deepEqual(pm.execution.location.current, 'R1');
+                        ` }, {
+                        legacy: {
+                            _itemName: 'request-name',
+                            _itemId: 'request-id',
+                            _itemPath: ['C1', 'R1'],
+                            _eventItemName: 'R1'
+                        }
+                    }, done);
+                });
+            });
+        });
     });
 });

types/index.d.ts

@@ -68,6 +68,14 @@ declare class PostmanCookieJar {
  */
 declare var pm: Postman;
 
+/**
+ * @param current - Current item name, current item is the item whose script is being executed
+ * @param rest - Arguments to pass to Array constructor
+ */
+declare class ExecutionLocation {
+    constructor(current: string, ...rest: string[]);
+}
+
 /**
  * @property async - true if the executed script was async, false otherwise
  * @property visualizer - visualizer data
@@ -183,6 +191,17 @@ declare interface Execution {
      * Stops the current request and its scripts from executing.
      */
     skipRequest(): void;
+    /**
+     * The path of the current request.
+     */
+    location: ExecutionLocationInterface;
+}
+
+declare interface ExecutionLocationInterface extends Array<string> {
+    /**
+     * The element name whose script is currently being executed.
+     */
+    current: string;
 }
 
 /**

types/sandbox/prerequest.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for postman-sandbox 4.2.8
+// Type definitions for postman-sandbox 4.3.0
 // Project: https://github.com/postmanlabs/postman-sandbox
 // Definitions by: PostmanLabs
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -112,6 +112,17 @@ declare interface Execution {
      * @excludeFromTestScript
      */
     skipRequest(): void;
+    /**
+     * The path of the current request.
+     */
+    location: ExecutionLocationInterface;
+}
+
+declare interface ExecutionLocationInterface extends Array {
+    /**
+     * The element name whose script is currently being executed.
+     */
+    current: string;
 }
 
 /**

types/sandbox/test.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for postman-sandbox 4.2.8
+// Type definitions for postman-sandbox 4.3.0
 // Project: https://github.com/postmanlabs/postman-sandbox
 // Definitions by: PostmanLabs
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -113,6 +113,17 @@ declare interface Visualizer {
 }
 
 declare interface Execution {
+    /**
+     * The path of the current request.
+     */
+    location: ExecutionLocationInterface;
+}
+
+declare interface ExecutionLocationInterface extends Array {
+    /**
+     * The element name whose script is currently being executed.
+     */
+    current: string;
 }
 
 /**