Deprecate access to Suite objects via this in describes

Jasmine 1.x exposed Suite objects to user code as the `this` in describe
functions. That should have been removed in 2.0 but it was missed. It
will be removed in 4.0. This change adds a deprecation warning if anything
on a describe's `this` is accessed.

The deprecation warning relies on Proxy, and won't work in environments
that don't have it. Among Jasmine's supported environments, that's Safari 9,
Safari 8, and all versions of IE. In those browsers, a describe's `this`
will still be a Suite for now, but there will be no deprecation warnings.

lib/jasmine-core/jasmine.js

@@ -65,6 +65,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
     j$.Clock = jRequire.Clock();
     j$.DelayedFunctionScheduler = jRequire.DelayedFunctionScheduler(j$);
     j$.Env = jRequire.Env(j$);
+    j$.deprecatingThisProxy = jRequire.deprecatingThisProxy(j$);
     j$.StackTrace = jRequire.StackTrace(j$);
     j$.ExceptionFormatter = jRequire.ExceptionFormatter(j$);
     j$.ExpectationFilterChain = jRequire.ExpectationFilterChain();
@@ -2139,7 +2140,7 @@ getJasmineRequireObj().Env = function(j$) {
 
       var declarationError = null;
       try {
-        specDefinitions.call(suite);
+        specDefinitions.call(j$.deprecatingThisProxy(suite, self));
       } catch (e) {
         declarationError = e;
       }
@@ -3673,6 +3674,39 @@ getJasmineRequireObj().DelayedFunctionScheduler = function(j$) {
   return DelayedFunctionScheduler;
 };
 
+/* eslint-disable compat/compat */
+// TODO: Remove this in the next major release.
+getJasmineRequireObj().deprecatingThisProxy = function(j$) {
+  var msg = "Access to 'this' in describe functions is deprecated.";
+
+  try {
+    new Proxy({}, {});
+  } catch (e) {
+    // Environment does not support Poxy.
+    return function(suite) {
+      return suite;
+    };
+  }
+
+  function DeprecatingThisProxyHandler(env) {
+    this._env = env;
+  }
+
+  DeprecatingThisProxyHandler.prototype.get = function(target, prop, receiver) {
+    this._env.deprecated(msg);
+    return target[prop];
+  };
+
+  DeprecatingThisProxyHandler.prototype.set = function(target, prop, value) {
+    this._env.deprecated(msg);
+    return (target[prop] = value);
+  };
+
+  return function(suite, env) {
+    return new Proxy(suite, new DeprecatingThisProxyHandler(env));
+  };
+};
+
 getJasmineRequireObj().errors = function() {
   function ExpectationFailed() {}
 

spec/core/EnvSpec.js

@@ -445,4 +445,47 @@ describe('Env', function() {
       done();
     });
   });
+
+  it("deprecates access to 'this' in describes", function() {
+    jasmine.getEnv().requireProxy();
+    var msg = "Access to 'this' in describe functions is deprecated.",
+      ran = false;
+    spyOn(env, 'deprecated');
+
+    env.describe('a suite', function() {
+      expect(this.description).toEqual('a suite');
+      expect(env.deprecated).toHaveBeenCalledWith(msg);
+      env.deprecated.calls.reset();
+
+      this.foo = 1;
+      expect(env.deprecated).toHaveBeenCalledWith(msg);
+      expect(this.foo).toEqual(1);
+      env.deprecated.calls.reset();
+
+      expect(this.getFullName()).toEqual('a suite');
+      expect(env.deprecated).toHaveBeenCalledWith(msg);
+      env.deprecated.calls.reset();
+
+      env.it('has a spec');
+      ran = true;
+    });
+
+    expect(ran).toBeTrue();
+  });
+
+  // TODO: Remove this in the next major version. Suites were never meant to be
+  // exposed via describe 'this' in >= 2.0, and user code should not rely on it.
+  // This spec is just here to make sure we don't break user code that *does*
+  // rely on it in older browsers (without Proxy) while deprecating it.
+  it("sets 'this' to the Suite in describes", function() {
+    var suiteThis;
+    spyOn(env, 'deprecated');
+
+    env.describe('a suite', function() {
+      suiteThis = this;
+      env.it('has a spec');
+    });
+
+    expect(suiteThis).toBeInstanceOf(jasmineUnderTest.Suite);
+  });
 });

spec/helpers/checkForProxy.js

@@ -0,0 +1,17 @@
+/* eslint-disable compat/compat */
+(function(env) {
+  function hasProxyConstructor() {
+    try {
+      new Proxy({}, {});
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  env.requireProxy = function() {
+    if (!hasProxyConstructor()) {
+      env.pending('Environment does not support Proxy');
+    }
+  };
+})(jasmine.getEnv());

spec/support/jasmine-browser.js

@@ -22,6 +22,7 @@ module.exports = {
     'helpers/BrowserFlags.js',
     'helpers/checkForArrayBuffer.js',
     'helpers/checkForMap.js',
+    'helpers/checkForProxy.js',
     'helpers/checkForSet.js',
     'helpers/checkForSymbol.js',
     'helpers/checkForTypedArrays.js',

spec/support/jasmine.json

@@ -9,6 +9,7 @@
     "helpers/generator.js",
     "helpers/checkForArrayBuffer.js",
     "helpers/checkForMap.js",
+    "helpers/checkForProxy.js",
     "helpers/checkForSet.js",
     "helpers/checkForSymbol.js",
     "helpers/checkForTypedArrays.js",

src/core/Env.js

@@ -1137,7 +1137,7 @@ getJasmineRequireObj().Env = function(j$) {
 
       var declarationError = null;
       try {
-        specDefinitions.call(suite);
+        specDefinitions.call(j$.deprecatingThisProxy(suite, self));
       } catch (e) {
         declarationError = e;
       }

src/core/deprecatingThisProxy.js

@@ -0,0 +1,32 @@
+/* eslint-disable compat/compat */
+// TODO: Remove this in the next major release.
+getJasmineRequireObj().deprecatingThisProxy = function(j$) {
+  var msg = "Access to 'this' in describe functions is deprecated.";
+
+  try {
+    new Proxy({}, {});
+  } catch (e) {
+    // Environment does not support Poxy.
+    return function(suite) {
+      return suite;
+    };
+  }
+
+  function DeprecatingThisProxyHandler(env) {
+    this._env = env;
+  }
+
+  DeprecatingThisProxyHandler.prototype.get = function(target, prop, receiver) {
+    this._env.deprecated(msg);
+    return target[prop];
+  };
+
+  DeprecatingThisProxyHandler.prototype.set = function(target, prop, value) {
+    this._env.deprecated(msg);
+    return (target[prop] = value);
+  };
+
+  return function(suite, env) {
+    return new Proxy(suite, new DeprecatingThisProxyHandler(env));
+  };
+};

src/core/requireCore.js

@@ -43,6 +43,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
     j$.Clock = jRequire.Clock();
     j$.DelayedFunctionScheduler = jRequire.DelayedFunctionScheduler(j$);
     j$.Env = jRequire.Env(j$);
+    j$.deprecatingThisProxy = jRequire.deprecatingThisProxy(j$);
     j$.StackTrace = jRequire.StackTrace(j$);
     j$.ExceptionFormatter = jRequire.ExceptionFormatter(j$);
     j$.ExpectationFilterChain = jRequire.ExpectationFilterChain();