wip private api recorder

ECO-4821

docs/internal/private-api-usage.md

@@ -21,17 +21,25 @@ None
 
 ### `test/realtime/delta.test.js`
 
+Marked in code.
+
 - `channel._lastPayload.messageId = null`
   - to make decoding fail
 
+Note that this test passes an overridden VCDiff decoder, but some SDKs don't use a VCDiff decoder
+
 ### `test/realtime/encoding.test.js`
 
+Marked in code.
+
 - `var BufferUtils = Ably.Realtime.Platform.BufferUtils;`
 - `var Defaults = Ably.Rest.Platform.Defaults;`
   - just used for accessing library’s baked-in protocol version, to pass to `request()`
 
 ### `test/realtime/presence.test.js`
 
+Marked in code.
+
 - `var createPM = Ably.protocolMessageFromDeserialized;`
 - `var PresenceMessage = Ably.Realtime.PresenceMessage;`
 - replacing `channel.sendPresence` with a version that checks the presence message’s client ID

test/common/globals/named_dependencies.js

@@ -13,5 +13,9 @@ define(function () {
     shared_helper: { browser: 'test/common/modules/shared_helper', node: 'test/common/modules/shared_helper' },
     async: { browser: 'node_modules/async/lib/async' },
     chai: { browser: 'node_modules/chai/chai', node: 'node_modules/chai/chai' },
+    private_api_recorder: {
+      browser: 'test/common/modules/private_api_recorder',
+      node: 'test/common/modules/private_api_recorder',
+    },
   });
 });

test/common/modules/private_api_recorder.js

@@ -0,0 +1,54 @@
+'use strict';
+
+define([], function () {
+  const privateAPIIdentifiers = [
+    'modifyChannelLastPayload',
+    'BufferUtils.hexEncode',
+    'BufferUtils.base64Decode',
+    'readDefaults.protocolVersion',
+    'protocolMessageFromDeserialized',
+    'Utils.mixin',
+    'PresenceMessage.fromValues',
+    'replaceChannelSendPresence',
+    'callChannelSendPresence',
+    'listen.connectionManager.transport.active',
+    'replace.transport.send',
+    'call.transport.send',
+    'call.presence.waitSync',
+    'read.connectionManager.connectionId',
+    'call.presence._myMembers.put',
+    'call.channel.sync',
+    'replace.channel.attachImpl',
+    'call.channel.checkPendingState',
+    'call.Platform.nextTick',
+    'call.channel.processMessage',
+    'call.EventEmitter.emit',
+  ];
+
+  class PrivateApiRecorder {
+    privateAPIUsages = [];
+
+    /**
+     * Creates a recording context for the current Mocha test case.
+     *
+     * @param testCase The value of `this` inside a Mocha test case.
+     */
+    createContext(testCase) {
+      if (!testCase) {
+        throw new Error('No test case passed to createContext');
+      }
+
+      return {
+        record: (privateAPIIdentifier) => {
+          console.log(`recorded private API in test ${testCase.test.fullTitle()}: ${privateAPIIdentifier}`);
+          if (privateAPIIdentifiers.indexOf(privateAPIIdentifier) == -1) {
+            throw new Error('Recorded unknown private API:', privateAPIIdentifier);
+          }
+          this.privateAPIUsages.push({ testCase, privateAPIIdentifier });
+        },
+      };
+    }
+  }
+
+  return (module.exports = new PrivateApiRecorder());
+});

test/realtime/delta.test.js

@@ -1,6 +1,12 @@
 'use strict';
 
-define(['shared_helper', 'vcdiff-decoder', 'async', 'chai'], function (helper, vcdiffDecoder, async, chai) {
+define(['shared_helper', 'vcdiff-decoder', 'async', 'chai', 'private_api_recorder'], function (
+  helper,
+  vcdiffDecoder,
+  async,
+  chai,
+  privateApiRecorder,
+) {
   var expect = chai.expect;
   var displayError = helper.displayError;
   var closeAndFinish = helper.closeAndFinish;
@@ -130,6 +136,8 @@ define(['shared_helper', 'vcdiff-decoder', 'async', 'chai'], function (helper, v
     });
 
     it('lastMessageNotFoundRecovery', function (done) {
+      const privateApiContext = privateApiRecorder.createContext(this);
+
       var testName = 'lastMessageNotFoundRecovery';
       try {
         var testVcdiffDecoder = getTestVcdiffDecoder();
@@ -154,6 +162,7 @@ define(['shared_helper', 'vcdiff-decoder', 'async', 'chai'], function (helper, v
 
             if (index === 1) {
               /* Simulate issue */
+              context.record('modifyChannelLastPayload');
               channel._lastPayload.messageId = null;
               channel.once('attaching', function (stateChange) {
                 try {

test/realtime/encoding.test.js

@@ -1,6 +1,12 @@
 'use strict';
 
-define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async, chai) {
+define(['ably', 'shared_helper', 'async', 'chai', 'private_api_recorder'], function (
+  Ably,
+  helper,
+  async,
+  chai,
+  privateApiRecorder,
+) {
   var expect = chai.expect;
   var loadTestData = helper.loadTestData;
   var BufferUtils = Ably.Realtime.Platform.BufferUtils;
@@ -27,6 +33,8 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
      * realtime, and check everything decodes correctly
      */
     it('message_decoding', function (done) {
+      const privateApiContext = privateApiRecorder.createContext(this);
+
       loadTestData(encodingFixturesPath, function (err, testData) {
         if (err) {
           done(err);
@@ -64,6 +72,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
                       channel.subscribe(name, function (msg) {
                         try {
                           if (encodingSpec.expectedHexValue) {
+                            privateApiContext.record('BufferUtils.hexEncode');
                             expect(BufferUtils.hexEncode(msg.data)).to.equal(
                               encodingSpec.expectedHexValue,
                               'Check data matches',
@@ -82,6 +91,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
                       binarychannel.subscribe(name, function (msg) {
                         try {
                           if (encodingSpec.expectedHexValue) {
+                            privateApiContext.record('BufferUtils.hexEncode');
                             expect(BufferUtils.hexEncode(msg.data)).to.equal(
                               encodingSpec.expectedHexValue,
                               'Check data matches',
@@ -97,6 +107,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
                       });
                     },
                     function (parallelCb) {
+                      privateApiContext.record('readDefaults.protocolVersion');
                       whenPromiseSettles(
                         realtime.request(
                           'post',
@@ -128,6 +139,8 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
      * manually, and check everything was encoded correctly
      */
     it('message_encoding', function (done) {
+      const privateApiContext = privateApiRecorder.createContext(this);
+
       loadTestData(encodingFixturesPath, function (err, testData) {
         if (err) {
           done(new Error('Unable to get test assets; err = ' + displayError(err)));
@@ -161,6 +174,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
                 var data,
                   name = index.toString();
                 if (encodingSpec.expectedHexValue) {
+                  privateApiContext.record('BufferUtils.base64Decode');
                   data = BufferUtils.base64Decode(encodingSpec.data);
                 } else {
                   data = encodingSpec.expectedValue;
@@ -179,6 +193,7 @@ define(['ably', 'shared_helper', 'async', 'chai'], function (Ably, helper, async
                       eachOfCb(err);
                       return;
                     }
+                    privateApiContext.record('readDefaults.protocolVersion');
                     whenPromiseSettles(
                       realtime.request('get', channelPath, Defaults.protocolVersion, null, null, null),
                       function (err, resultPage) {

test/realtime/event_emitter.test.js

@@ -1,6 +1,6 @@
 'use strict';
 
-define(['shared_helper', 'chai'], function (helper, chai) {
+define(['shared_helper', 'chai', 'private_api_recorder'], function (helper, chai, privateApiRecorder) {
   var expect = chai.expect;
   var displayError = helper.displayError;
   var closeAndFinish = helper.closeAndFinish;
@@ -70,6 +70,8 @@ define(['shared_helper', 'chai'], function (helper, chai) {
     });
 
     it('emitCallsAllCallbacksIgnoringExceptions', function (done) {
+      const privateApiContext = privateApiRecorder.createContext(this);
+
       var realtime = helper.AblyRealtime({ autoConnect: false }),
         callbackCalled = false,
         eventEmitter = realtime.connection;
@@ -84,6 +86,7 @@ define(['shared_helper', 'chai'], function (helper, chai) {
         callbackCalled = true;
       });
 
+      privateApiContext.record('call.EventEmitter.emit');
       eventEmitter.emit('custom');
       try {
         expect(callbackCalled, 'Last callback should have been called').to.be.ok;