add pm.message

lib/sandbox/execution.js

@@ -6,7 +6,8 @@ const _ = require('lodash'),
         SCRIPT: 'script',
         DATA: 'data',
         COOKIES: 'cookies',
-        RESPONSE: 'response'
+        RESPONSE: 'response',
+        MESSAGE: 'message'
     },
 
     TARGETS_WITH_REQUEST = {
@@ -18,6 +19,11 @@ const _ = require('lodash'),
         test: true
     },
 
+    TARGETS_WITH_MESSAGE = {
+        onIncomingMessage: true,
+        onOutgoingMessage: true
+    },
+
     CONTEXT_VARIABLE_SCOPES = ['_variables', 'environment', 'collectionVariables', 'globals'],
 
     trackingOptions = { autoCompact: true };
@@ -42,10 +48,11 @@ class Execution {
         });
 
         if (options.initializeExecution) {
-            const { request, response } = options.initializeExecution(this.target, context) || {};
+            const { request, response, message } = options.initializeExecution(this.target, context) || {};
 
             this.request = request;
             this.response = response;
+            this.message = message;
         }
         else {
             if (TARGETS_WITH_REQUEST[this.target] || _.has(context, PROPERTY.REQUEST)) {
@@ -68,6 +75,17 @@ class Execution {
                 this.response = sdk.Response.isResponse(context.response) ?
                     context.response : new sdk.Response(context.response);
             }
+
+            if (TARGETS_WITH_MESSAGE[this.target] || _.has(context, PROPERTY.MESSAGE)) {
+                /**
+                 * @note:
+                 * this reference is passed on as `pm.message`, pm api adds helper functions like `to` to `pm.response`
+                 * sandbox overrides collection Response.prototype.toJSON to remove helpers before toJSON,
+                 * see `purse.js`
+                 */
+                this.message = sdk.message?.isMessage(context.message) ?
+                    context.message : sdk.Message && new sdk.Message(context.message);
+            }
         }
 
         /**

lib/sandbox/index.js

@@ -2,7 +2,7 @@
  * @license Copyright 2016 Postdot Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
+ * you may not use this file except in complian ce with the License.
  * You may obtain a copy of the License at
  *
  *    http://www.apache.org/licenses/LICENSE-2.0

lib/sandbox/pmapi.js

@@ -205,6 +205,15 @@ function Postman (execution, onRequest, onSkipRequest, onAssertion, cookieStore,
          */
         response: execution.response,
 
+        /**
+         * Only available in on message sent and received scripts. pm.message contains information about
+         * an individual message (varies by protocol) received from a server or sent from the client
+         * that the script is being run on.
+         *
+         * @type {Object}
+         */
+        message: execution.message,
+
         /**
          * The cookies object contains a list of cookies that are associated with the domain
          * to which the request was made.
@@ -398,6 +407,15 @@ function Postman (execution, onRequest, onSkipRequest, onAssertion, cookieStore,
             }
         });
     }
+    // add message assertions
+    if (this.message) {
+        // these are removed before serializing see `purse.js`
+        Object.defineProperty(this.message, 'to', {
+            get () {
+                return chai.expect(this).to;
+            }
+        });
+    }
 
     iterationData = null; // precautionary
 }

types/index.d.ts

@@ -196,6 +196,15 @@ declare class Postman {
      * to the response that was received.
      */
     response: Response;
+    /**
+     * Only available in on message sent and received scripts. pm.message contains information about
+     * an individual message (varies by protocol) received from a server or sent from the client
+     * that the script is being run on.
+     *
+     * TODO: define message type
+     * @type {Object}
+     */
+    message: any;
     /**
      * The cookies object contains a list of cookies that are associated with the domain
      * to which the request was made.
@@ -284,6 +293,7 @@ declare interface Visualizer {
 declare interface Execution {
     request: any;
     response: any;
+    message: any;
     /**
      * Stops the current request and its scripts from executing.
      */