admin/jasmine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improved readability of matcher-related deprecations

Browse Source 
* Include stack traces. This makes it easier to find the matcher that
needs to be updated, particularly when it comes from a library rather
than the user's own code.

* Show each deprecation only once unless `config.verboseDeprecations`
is set. Since matchers are often added in a global `beforeEach`, logging
deprecations every time can be overwhelming.
This commit is contained in:
Steve Gravrock
2020-01-18 10:39:51 -08:00
committed by Steve Gravrock
parent 90d6f9d73c
commit 9aed55bb91
11 changed files with 216 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
lib/jasmine-core/jasmine.js
View File

@@ -80,7 +80,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
j$.basicPrettyPrinter_ = j$.makePrettyPrinter();
Object.defineProperty(j$, 'pp', {
get: function() {
j$.getEnv().deprecated(
j$.getEnv().deprecatedOnceWithStack(
'jasmine.pp is deprecated and will be removed in a future release. ' +
'Use the pp method of the matchersUtil passed to the matcher factory ' +
"or the asymmetric equality tester's `asymmetricMatch` method " +
@@ -97,7 +97,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
});
Object.defineProperty(j$, 'matchersUtil', {
get: function() {
j$.getEnv().deprecated(
j$.getEnv().deprecatedOnceWithStack(
'jasmine.matchersUtil is deprecated and will be removed ' +
'in a future release. Use the instance passed to the matcher factory or ' +
"the asymmetric equality tester's `asymmetricMatch` method instead. " +
@@ -981,6 +981,7 @@ getJasmineRequireObj().Env = function(j$) {
var currentlyExecutingSuites = [];
var currentDeclarationSuite = null;
var hasFailures = false;
var deprecationsToSuppress = [];
/**
* This represents the available options to configure Jasmine.
@@ -1060,7 +1061,19 @@ getJasmineRequireObj().Env = function(j$) {
* @type function
* @default undefined
*/
Promise: undefined
Promise: undefined,
/**
* Whether or not to issue warnings for certain deprecated functionality
* every time it's used. If not set or set to false, deprecation warnings
* for methods that tend to be called frequently will be issued only once
* or otherwise throttled to to prevent the suite output from being flooded
* with warnings.
* @name Configuration#verboseDeprecations
* @since 3.6.0
* @type Boolean
* @default false
*/
verboseDeprecations: false
};
var currentSuite = function() {
@@ -1154,6 +1167,10 @@ getJasmineRequireObj().Env = function(j$) {
);
}
}
if (configuration.hasOwnProperty('verboseDeprecations')) {
config.verboseDeprecations = configuration.verboseDeprecations;
}
};
/**
@@ -1228,7 +1245,7 @@ getJasmineRequireObj().Env = function(j$) {
for (var matcherName in matchersToAdd) {
if (matchersToAdd[matcherName].length > 1) {
self.deprecated(
self.deprecatedOnceWithStack(
'The matcher factory for "' +
matcherName +
'" ' +
@@ -1253,7 +1270,7 @@ getJasmineRequireObj().Env = function(j$) {
for (var matcherName in matchersToAdd) {
if (matchersToAdd[matcherName].length > 1) {
self.deprecated(
self.deprecatedOnceWithStack(
'The matcher factory for "' +
matcherName +
'" ' +
@@ -1561,6 +1578,29 @@ getJasmineRequireObj().Env = function(j$) {
}
};
this.deprecatedOnceWithStack = function(deprecation) {
var formatter = new j$.ExceptionFormatter(),
stackTrace = formatter
.stack(j$.util.errorWithStack())
.replace(/^Error\n/m, '');
if (config.verboseDeprecations) {
this.deprecated(deprecation + '\n' + stackTrace);
} else {
if (deprecationsToSuppress.indexOf(deprecation) === -1) {
this.deprecated(
deprecation +
'\n' +
'Note: This message will be shown only once. ' +
'Set config.verboseDeprecations to true to see every occurrence.\n' +
stackTrace
);
}
deprecationsToSuppress.push(deprecation);
}
};
var queueRunnerFactory = function(options, args) {
var failFast = false;
if (options.isLeaf) {
@@ -4489,9 +4529,9 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
*/
MatchersUtil.prototype.contains = function(haystack, needle, customTesters) {
if (customTesters) {
j$.getEnv().deprecated('Passing custom equality testers to ' +
'MatchersUtil#contains is deprecated. See ' +
'<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
j$.getEnv().deprecatedOnceWithStack('Passing custom equality testers ' +
'to MatchersUtil#contains is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
}
if (j$.isSet(haystack)) {
@@ -4593,14 +4633,14 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
diffBuilder = customTestersOrDiffBuilder;
} else {
if (customTestersOrDiffBuilder) {
j$.getEnv().deprecated('Passing custom equality testers to ' +
'MatchersUtil#equals is deprecated. See ' +
'<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
j$.getEnv().deprecatedOnceWithStack('Passing custom equality testers ' +
'to MatchersUtil#equals is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
}
if (diffBuilderOrNothing) {
j$.getEnv().deprecated('Diff builder should be passed as the third argument ' +
'to MatchersUtil#equals, not the fourth. ' +
j$.getEnv().deprecatedOnceWithStack('Diff builder should be passed ' +
'as the third argument to MatchersUtil#equals, not the fourth. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
}

54
spec/core/EnvSpec.js
View File

@@ -281,6 +281,60 @@ describe('Env', function() {
});
});
describe('#deprecatedOnceWithStack', function() {
it('includes a stack trace', function() {
spyOn(env, 'deprecated');
env.deprecatedOnceWithStack('msg');
expect(env.deprecated).toHaveBeenCalled();
var msg = env.deprecated.calls.argsFor(0)[0];
expect(msg).toContain('msg');
expect(msg).toContain('EnvSpec.js');
expect(msg).not.toContain('Error');
});
describe('When verboseDeprecations is true', function() {
it('calls #deprecated every time', function() {
env.configure({ verboseDeprecations: true });
spyOn(env, 'deprecated');
env.deprecatedOnceWithStack('msg');
env.deprecatedOnceWithStack('msg');
expect(env.deprecated).toHaveBeenCalledWith(
jasmine.stringMatching(/msg/)
);
expect(env.deprecated).toHaveBeenCalledTimes(2);
expect(env.deprecated).not.toHaveBeenCalledWith(
jasmine.stringMatching(/only once/)
);
});
});
describe('When verboseDeprecations is false', function() {
it('calls #deprecated once per unique message', function() {
env.configure({ verboseDeprecations: false });
spyOn(env, 'deprecated');
env.deprecatedOnceWithStack('foo');
env.deprecatedOnceWithStack('bar');
env.deprecatedOnceWithStack('foo');
expect(env.deprecated).toHaveBeenCalledWith(
jasmine.stringMatching(
/foo\nNote: This message will be shown only once. Set config.verboseDeprecations to true to see every occurrence/m
)
);
expect(env.deprecated).toHaveBeenCalledWith(
jasmine.stringMatching(
/bar\nNote: This message will be shown only once. Set config.verboseDeprecations to true to see every occurrence/m
)
);
expect(env.deprecated).toHaveBeenCalledTimes(2);
});
});
});
describe('when not constructed with suppressLoadErrors: true', function() {
it('installs a global error handler on construction', function() {
var globalErrors = jasmine.createSpyObj('globalErrors', [

23
spec/core/integration/CustomAsyncMatchersSpec.js
View File

@@ -148,22 +148,33 @@ describe('Custom Async Matchers (Integration)', function() {
env.execute();
});
it('logs a deprecation warning if the matcher factory takes two arguments', function (done) {
it('logs a deprecation once per matcher if the matcher factory takes two arguments', function (done) {
var matcherFactory = function (matchersUtil, customEqualityTesters) {
return { compare: function () {} };
};
spyOn(env, 'deprecated');
env.it('a spec', function() {
env.beforeEach(function() {
env.addAsyncMatchers({toBeFoo: matcherFactory});
env.addAsyncMatchers({toBeBar: matcherFactory});
});
env.it('a spec', function() {});
env.it('another spec', function() {});
function jasmineDone() {
expect(env.deprecated).toHaveBeenCalledWith('The matcher factory for "toBeFoo" ' +
'accepts custom equality testers, but this parameter will no longer be passed ' +
'in a future release. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
expect(env.deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'The matcher factory for "toBeFoo" accepts custom equality testers, ' +
'but this parameter will no longer be passed in a future release. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
expect(env.deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'The matcher factory for "toBeBar" accepts custom equality testers, ' +
'but this parameter will no longer be passed in a future release. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
expect(env.deprecated).toHaveBeenCalledTimes(2);
done();
}

23
spec/core/integration/CustomMatchersSpec.js
View File

@@ -267,22 +267,33 @@ describe("Custom Matchers (Integration)", function () {
env.execute();
});
it('logs a deprecation warning if the matcher factory takes two arguments', function(done) {
it('logs a deprecation once per matcher if the matcher factory takes two arguments', function(done) {
var matcherFactory = function (matchersUtil, customEqualityTesters) {
return { compare: function() {} };
};
spyOn(env, 'deprecated');
env.it('a spec', function() {
env.beforeEach(function() {
env.addMatchers({toBeFoo: matcherFactory});
env.addMatchers({toBeBar: matcherFactory});
});
env.it('a spec', function() {});
env.it('another spec', function() {});
function jasmineDone() {
expect(env.deprecated).toHaveBeenCalledWith('The matcher factory for "toBeFoo" ' +
'accepts custom equality testers, but this parameter will no longer be passed ' +
'in a future release. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
expect(env.deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'The matcher factory for "toBeFoo" accepts custom equality testers, ' +
'but this parameter will no longer be passed in a future release. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
expect(env.deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'The matcher factory for "toBeBar" accepts custom equality testers, ' +
'but this parameter will no longer be passed in a future release. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
expect(env.deprecated).toHaveBeenCalledTimes(2);
done();
}

21
spec/core/matchers/matchersUtilSpec.js
View File

@@ -856,20 +856,26 @@ describe("matchersUtil", function() {
matchersUtil.equals(0, 0, []);
expect(deprecated).toHaveBeenCalledWith('Passing custom equality testers ' +
expect(deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'Passing custom equality testers ' +
'to MatchersUtil#equals is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
});
it('logs a deprecation warning when a diffBuilder is provided as the fourth argument', function() {
var matchersUtil = new jasmineUnderTest.MatchersUtil(),
deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated');
debugger;
matchersUtil.equals(0, 0, null, new jasmineUnderTest.NullDiffBuilder());
expect(deprecated).toHaveBeenCalledWith('Diff builder should be passed as the ' +
expect(deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'Diff builder should be passed as the ' +
'third argument to MatchersUtil#equals, not the fourth. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
});
it('uses a diffBuilder if one is provided as the fourth argument', function() {
@@ -936,9 +942,10 @@ describe("matchersUtil", function() {
expect(matchersUtil.contains([1, 2], 3, [customTester])).toBe(true);
expect(deprecated).toHaveBeenCalledWith('Passing custom equality testers ' +
'to MatchersUtil#contains is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
expect(deprecated).toHaveBeenCalledWith(jasmine.stringMatching(
'Passing custom equality testers to MatchersUtil#contains is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
));
});
it("uses custom equality testers if passed to the constructor and actual is an Array", function() {

4
spec/helpers/resetEnv.js Normal file
View File

@@ -0,0 +1,4 @@
beforeEach(function() {
// env is stateful. Ensure that it does not leak between tests.
jasmineUnderTest.currentEnv_ = null;
});

3
spec/support/jasmine-browser.js
View File

@@ -27,7 +27,8 @@ module.exports = {
'helpers/integrationMatchers.js',
'helpers/promises.js',
'helpers/requireFastCheck.js',
'helpers/defineJasmineUnderTest.js'
'helpers/defineJasmineUnderTest.js',
'helpers/resetEnv.js'
],
random: true,
browser: {

3
spec/support/jasmine.json
View File

@@ -14,7 +14,8 @@
"helpers/integrationMatchers.js",
"helpers/promises.js",
"helpers/requireFastCheck.js",
"helpers/nodeDefineJasmineUnderTest.js"
"helpers/nodeDefineJasmineUnderTest.js",
"helpers/resetEnv.js"
],
"random": true
}

46
src/core/Env.js
View File

@@ -32,6 +32,7 @@ getJasmineRequireObj().Env = function(j$) {
var currentlyExecutingSuites = [];
var currentDeclarationSuite = null;
var hasFailures = false;
var deprecationsToSuppress = [];
/**
* This represents the available options to configure Jasmine.
@@ -111,7 +112,19 @@ getJasmineRequireObj().Env = function(j$) {
* @type function
* @default undefined
*/
Promise: undefined
Promise: undefined,
/**
* Whether or not to issue warnings for certain deprecated functionality
* every time it's used. If not set or set to false, deprecation warnings
* for methods that tend to be called frequently will be issued only once
* or otherwise throttled to to prevent the suite output from being flooded
* with warnings.
* @name Configuration#verboseDeprecations
* @since 3.6.0
* @type Boolean
* @default false
*/
verboseDeprecations: false
};
var currentSuite = function() {
@@ -205,6 +218,10 @@ getJasmineRequireObj().Env = function(j$) {
);
}
}
if (configuration.hasOwnProperty('verboseDeprecations')) {
config.verboseDeprecations = configuration.verboseDeprecations;
}
};
/**
@@ -279,7 +296,7 @@ getJasmineRequireObj().Env = function(j$) {
for (var matcherName in matchersToAdd) {
if (matchersToAdd[matcherName].length > 1) {
self.deprecated(
self.deprecatedOnceWithStack(
'The matcher factory for "' +
matcherName +
'" ' +
@@ -304,7 +321,7 @@ getJasmineRequireObj().Env = function(j$) {
for (var matcherName in matchersToAdd) {
if (matchersToAdd[matcherName].length > 1) {
self.deprecated(
self.deprecatedOnceWithStack(
'The matcher factory for "' +
matcherName +
'" ' +
@@ -612,6 +629,29 @@ getJasmineRequireObj().Env = function(j$) {
}
};
this.deprecatedOnceWithStack = function(deprecation) {
var formatter = new j$.ExceptionFormatter(),
stackTrace = formatter
.stack(j$.util.errorWithStack())
.replace(/^Error\n/m, '');
if (config.verboseDeprecations) {
this.deprecated(deprecation + '\n' + stackTrace);
} else {
if (deprecationsToSuppress.indexOf(deprecation) === -1) {
this.deprecated(
deprecation +
'\n' +
'Note: This message will be shown only once. ' +
'Set config.verboseDeprecations to true to see every occurrence.\n' +
stackTrace
);
}
deprecationsToSuppress.push(deprecation);
}
};
var queueRunnerFactory = function(options, args) {
var failFast = false;
if (options.isLeaf) {

16
src/core/matchers/matchersUtil.js
View File

@@ -34,9 +34,9 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
*/
MatchersUtil.prototype.contains = function(haystack, needle, customTesters) {
if (customTesters) {
j$.getEnv().deprecated('Passing custom equality testers to ' +
'MatchersUtil#contains is deprecated. See ' +
'<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
j$.getEnv().deprecatedOnceWithStack('Passing custom equality testers ' +
'to MatchersUtil#contains is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
}
if (j$.isSet(haystack)) {
@@ -138,14 +138,14 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
diffBuilder = customTestersOrDiffBuilder;
} else {
if (customTestersOrDiffBuilder) {
j$.getEnv().deprecated('Passing custom equality testers to ' +
'MatchersUtil#equals is deprecated. See ' +
'<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
j$.getEnv().deprecatedOnceWithStack('Passing custom equality testers ' +
'to MatchersUtil#equals is deprecated. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
}
if (diffBuilderOrNothing) {
j$.getEnv().deprecated('Diff builder should be passed as the third argument ' +
'to MatchersUtil#equals, not the fourth. ' +
j$.getEnv().deprecatedOnceWithStack('Diff builder should be passed ' +
'as the third argument to MatchersUtil#equals, not the fourth. ' +
'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
}

4
src/core/requireCore.js
View File

@@ -58,7 +58,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
j$.basicPrettyPrinter_ = j$.makePrettyPrinter();
Object.defineProperty(j$, 'pp', {
get: function() {
j$.getEnv().deprecated(
j$.getEnv().deprecatedOnceWithStack(
'jasmine.pp is deprecated and will be removed in a future release. ' +
'Use the pp method of the matchersUtil passed to the matcher factory ' +
"or the asymmetric equality tester's `asymmetricMatch` method " +
@@ -75,7 +75,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
});
Object.defineProperty(j$, 'matchersUtil', {
get: function() {
j$.getEnv().deprecated(
j$.getEnv().deprecatedOnceWithStack(
'jasmine.matchersUtil is deprecated and will be removed ' +
'in a future release. Use the instance passed to the matcher factory or ' +
"the asymmetric equality tester's `asymmetricMatch` method instead. " +