mirror of
https://github.com/zebrajr/react.git
synced 2026-01-15 12:15:22 +00:00
Add pragma for feature testing: @gate (#18581)
* Add pragma for feature testing: @gate
The `@gate` pragma declares under which conditions a test is expected to
pass.
If the gate condition passes, then the test runs normally (same as if
there were no pragma).
If the conditional fails, then the test runs and is *expected to fail*.
An alternative to `it.experimental` and similar proposals.
Examples
--------
Basic:
```js
// @gate enableBlocksAPI
test('passes only if Blocks API is available', () => {/*...*/})
```
Negation:
```js
// @gate !disableLegacyContext
test('depends on a deprecated feature', () => {/*...*/})
```
Multiple flags:
```js
// @gate enableNewReconciler
// @gate experimental
test('needs both useEvent and Blocks', () => {/*...*/})
```
Logical operators (yes, I'm sorry):
```js
// @gate experimental && (enableNewReconciler || disableSchedulerTimeoutBasedOnReactExpirationTime)
test('concurrent mode, doesn\'t work in old fork unless Scheduler timeout flag is disabled', () => {/*...*/})
```
Strings, and comparion operators
No use case yet but I figure eventually we'd use this to gate on
different release channels:
```js
// @gate channel === "experimental" || channel === "modern"
test('works in OSS experimental or www modern', () => {/*...*/})
```
How does it work?
I'm guessing those last two examples might be controversial. Supporting
those cases did require implementing a mini-parser.
The output of the transform is very straightforward, though.
Input:
```js
// @gate a && (b || c)
test('some test', () => {/*...*/})
```
Output:
```js
_test_gate(ctx => ctx.a && (ctx.b || ctx.c, 'some test'), () => {/*...*/});
```
It also works with `it`, `it.only`, and `fit`. It leaves `it.skip` and
`xit` alone because those tests are disabled anyway.
`_test_gate` is a global method that I set up in our Jest config. It
works about the same as the existing `it.experimental` helper.
The context (`ctx`) argument is whatever we want it to be. I set it up
so that it throws if you try to access a flag that doesn't exist. I also
added some shortcuts for common gating conditions, like `old`
and `new`:
```js
// @gate experimental
test('experimental feature', () => {/*...*/})
// @gate new
test('only passes in new reconciler', () => {/*...*/})
```
Why implement this as a pragma instead of a runtime API?
- Doesn't require monkey patching built-in Jest methods. Instead it
compiles to a runtime function that composes Jest's API.
- Will be easy to upgrade if Jest ever overhauls their API or we switch
to a different testing framework (unlikely but who knows).
- It feels lightweight so hopefully people won't feel gross using it.
For example, adding or removing a gate pragma will never affect the
indentation of the test, unlike if you wrapped the test in a
conditional block.
* Compatibility with console error/warning tracking
We patch console.error and console.warning to track unexpected calls
in our tests. If there's an unexpected call, we usually throw inside
an `afterEach` hook. However, that's too late for tests that we
expect to fail, because our `_test_gate` runtime can't capture the
error. So I also check for unexpected calls inside `_test_gate`.
* Move test flags to dedicated file
Added some instructions for how the flags are set up and how to
use them.
* Add dynamic version of gate API
Receives same flags as the pragma.
If we ever decide to revert the pragma, we can codemod them to use
this instead.
This commit is contained in:
Andrew Clark
201
scripts/babel/__tests__/transform-test-gate-pragma-test.js
Normal file
201
scripts/babel/__tests__/transform-test-gate-pragma-test.js
Normal file
@@ -0,0 +1,201 @@
|
||||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
'use strict';
|
||||
|
||||
describe('transform-test-gate-pragma', () => {
|
||||
// Fake runtime
|
||||
// eslint-disable-next-line no-unused-vars
|
||||
const _test_gate = (gateFn, testName, cb) => {
|
||||
test(testName, (...args) => {
|
||||
shouldPass = gateFn(context);
|
||||
return cb(...args);
|
||||
});
|
||||
};
|
||||
|
||||
// eslint-disable-next-line no-unused-vars
|
||||
const _test_gate_focus = (gateFn, testName, cb) => {
|
||||
// NOTE: Tests in this file are not actually focused because the calls to
|
||||
// `test.only` and `fit` are compiled to `_test_gate_focus`. So if you want
|
||||
// to focus something, swap the following `test` call for `test.only`.
|
||||
test(testName, (...args) => {
|
||||
shouldPass = gateFn(context);
|
||||
isFocused = true;
|
||||
return cb(...args);
|
||||
});
|
||||
};
|
||||
|
||||
// Feature flags, environment variables, etc. We can configure this in
|
||||
// our test set up.
|
||||
const context = {
|
||||
flagThatIsOff: false,
|
||||
flagThatIsOn: true,
|
||||
environment: 'fake-environment',
|
||||
};
|
||||
|
||||
let shouldPass;
|
||||
let isFocused;
|
||||
beforeEach(() => {
|
||||
shouldPass = null;
|
||||
isFocused = false;
|
||||
});
|
||||
|
||||
test('no pragma', () => {
|
||||
expect(shouldPass).toBe(null);
|
||||
});
|
||||
|
||||
// unrelated comment
|
||||
test('no pragma, unrelated comment', () => {
|
||||
expect(shouldPass).toBe(null);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn
|
||||
test('basic positive test', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOff
|
||||
test('basic negative test', () => {
|
||||
expect(shouldPass).toBe(false);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn
|
||||
it('it method', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
/* eslint-disable jest/no-focused-tests */
|
||||
|
||||
// @gate flagThatIsOn
|
||||
test.only('test.only', () => {
|
||||
expect(isFocused).toBe(true);
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOff
|
||||
it.only('it.only', () => {
|
||||
expect(isFocused).toBe(true);
|
||||
expect(shouldPass).toBe(false);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn
|
||||
fit('fit', () => {
|
||||
expect(isFocused).toBe(true);
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
/* eslint-enable jest/no-focused-tests */
|
||||
|
||||
// @gate !flagThatIsOff
|
||||
test('flag negation', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn
|
||||
// @gate !flagThatIsOff
|
||||
test('multiple gates', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn
|
||||
// @gate flagThatIsOff
|
||||
test('multiple gates 2', () => {
|
||||
expect(shouldPass).toBe(false);
|
||||
});
|
||||
|
||||
// @gate !flagThatIsOff && flagThatIsOn
|
||||
test('&&', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOff || flagThatIsOn
|
||||
test('||', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate (flagThatIsOn || flagThatIsOff) && flagThatIsOn
|
||||
test('groups', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn == !flagThatIsOff
|
||||
test('==', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn === !flagThatIsOff
|
||||
test('===', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn != !flagThatIsOff
|
||||
test('!=', () => {
|
||||
expect(shouldPass).toBe(false);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn != !flagThatIsOff
|
||||
test('!==', () => {
|
||||
expect(shouldPass).toBe(false);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOn === true
|
||||
test('true', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate flagThatIsOff === false
|
||||
test('false', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate environment === "fake-environment"
|
||||
test('double quoted strings', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
|
||||
// @gate environment === 'fake-environment'
|
||||
test('single quoted strings', () => {
|
||||
expect(shouldPass).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('transform test-gate-pragma: actual runtime', () => {
|
||||
// These tests use the actual gating runtime used by the rest of our
|
||||
// test suite.
|
||||
|
||||
// @gate __DEV__
|
||||
test('__DEV__', () => {
|
||||
if (!__DEV__) {
|
||||
throw Error("Doesn't work in production!");
|
||||
}
|
||||
});
|
||||
|
||||
// Always should fail because of the unguarded console.error
|
||||
// @gate false
|
||||
test('works with console.error tracking', () => {
|
||||
console.error('Should cause test to fail');
|
||||
});
|
||||
|
||||
// Always should fail because of the unguarded console.warn
|
||||
// @gate false
|
||||
test('works with console.warn tracking', () => {
|
||||
console.warn('Should cause test to fail');
|
||||
});
|
||||
|
||||
// @gate false
|
||||
test('works with console tracking if error is thrown before end of test', () => {
|
||||
console.warn('Please stop that!');
|
||||
console.error('Stop that!');
|
||||
throw Error('I told you to stop!');
|
||||
});
|
||||
});
|
||||
|
||||
describe('dynamic gate method', () => {
|
||||
// @gate experimental && __DEV__
|
||||
test('returns same conditions as pragma', () => {
|
||||
expect(gate(ctx => ctx.experimental && ctx.__DEV__)).toBe(true);
|
||||
});
|
||||
});
|
||||
330
scripts/babel/transform-test-gate-pragma.js
Normal file
330
scripts/babel/transform-test-gate-pragma.js
Normal file
@@ -0,0 +1,330 @@
|
||||
'use strict';
|
||||
|
||||
/* eslint-disable no-for-of-loops/no-for-of-loops */
|
||||
|
||||
function transform(babel) {
|
||||
const {types: t} = babel;
|
||||
|
||||
// A very stupid subset of pseudo-JavaScript, used to run tests conditionally
|
||||
// based on the environment.
|
||||
//
|
||||
// Input:
|
||||
// @gate a && (b || c)
|
||||
// test('some test', () => {/*...*/})
|
||||
//
|
||||
// Output:
|
||||
// @gate a && (b || c)
|
||||
// _test_gate(ctx => ctx.a && (ctx.b || ctx.c), 'some test', () => {/*...*/});
|
||||
//
|
||||
// expression → binary ( ( "||" | "&&" ) binary)* ;
|
||||
// binary → unary ( ( "==" | "!=" | "===" | "!==" ) unary )* ;
|
||||
// unary → "!" primary
|
||||
// | primary ;
|
||||
// primary → NAME | STRING | BOOLEAN
|
||||
// | "(" expression ")" ;
|
||||
function tokenize(code) {
|
||||
const tokens = [];
|
||||
let i = 0;
|
||||
while (i < code.length) {
|
||||
let char = code[i];
|
||||
// Double quoted strings
|
||||
if (char === '"') {
|
||||
let string = '';
|
||||
i++;
|
||||
do {
|
||||
if (i > code.length) {
|
||||
throw Error('Missing a closing quote');
|
||||
}
|
||||
char = code[i++];
|
||||
if (char === '"') {
|
||||
break;
|
||||
}
|
||||
string += char;
|
||||
} while (true);
|
||||
tokens.push({type: 'string', value: string});
|
||||
continue;
|
||||
}
|
||||
|
||||
// Single quoted strings
|
||||
if (char === "'") {
|
||||
let string = '';
|
||||
i++;
|
||||
do {
|
||||
if (i > code.length) {
|
||||
throw Error('Missing a closing quote');
|
||||
}
|
||||
char = code[i++];
|
||||
if (char === "'") {
|
||||
break;
|
||||
}
|
||||
string += char;
|
||||
} while (true);
|
||||
tokens.push({type: 'string', value: string});
|
||||
continue;
|
||||
}
|
||||
|
||||
// Whitespace
|
||||
if (/\s/.test(char)) {
|
||||
if (char === '\n') {
|
||||
return tokens;
|
||||
}
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
|
||||
const next3 = code.substring(i, i + 3);
|
||||
if (next3 === '===') {
|
||||
tokens.push({type: '=='});
|
||||
i += 3;
|
||||
continue;
|
||||
}
|
||||
if (next3 === '!==') {
|
||||
tokens.push({type: '!='});
|
||||
i += 3;
|
||||
continue;
|
||||
}
|
||||
|
||||
const next2 = code.substring(i, i + 2);
|
||||
switch (next2) {
|
||||
case '&&':
|
||||
case '||':
|
||||
case '==':
|
||||
case '!=':
|
||||
tokens.push({type: next2});
|
||||
i += 2;
|
||||
continue;
|
||||
}
|
||||
|
||||
switch (char) {
|
||||
case '(':
|
||||
case ')':
|
||||
case '!':
|
||||
tokens.push({type: char});
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Names
|
||||
const nameRegex = /[a-zA-Z_$][0-9a-zA-Z_$]*/y;
|
||||
nameRegex.lastIndex = i;
|
||||
const match = nameRegex.exec(code);
|
||||
if (match !== null) {
|
||||
const name = match[0];
|
||||
switch (name) {
|
||||
case 'true': {
|
||||
tokens.push({type: 'boolean', value: true});
|
||||
break;
|
||||
}
|
||||
case 'false': {
|
||||
tokens.push({type: 'boolean', value: false});
|
||||
break;
|
||||
}
|
||||
default: {
|
||||
tokens.push({type: 'name', name});
|
||||
}
|
||||
}
|
||||
i += name.length;
|
||||
continue;
|
||||
}
|
||||
|
||||
throw Error('Invalid character: ' + char);
|
||||
}
|
||||
return tokens;
|
||||
}
|
||||
|
||||
function parse(code, ctxIdentifier) {
|
||||
const tokens = tokenize(code);
|
||||
|
||||
let i = 0;
|
||||
function parseExpression() {
|
||||
let left = parseBinary();
|
||||
while (true) {
|
||||
const token = tokens[i];
|
||||
if (token !== undefined) {
|
||||
switch (token.type) {
|
||||
case '||':
|
||||
case '&&': {
|
||||
i++;
|
||||
const right = parseBinary();
|
||||
if (right === null) {
|
||||
throw Error('Missing expression after ' + token.type);
|
||||
}
|
||||
left = t.logicalExpression(token.type, left, right);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
return left;
|
||||
}
|
||||
|
||||
function parseBinary() {
|
||||
let left = parseUnary();
|
||||
while (true) {
|
||||
const token = tokens[i];
|
||||
if (token !== undefined) {
|
||||
switch (token.type) {
|
||||
case '==':
|
||||
case '!=': {
|
||||
i++;
|
||||
const right = parseUnary();
|
||||
if (right === null) {
|
||||
throw Error('Missing expression after ' + token.type);
|
||||
}
|
||||
left = t.binaryExpression(token.type, left, right);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
return left;
|
||||
}
|
||||
|
||||
function parseUnary() {
|
||||
const token = tokens[i];
|
||||
if (token !== undefined) {
|
||||
if (token.type === '!') {
|
||||
i++;
|
||||
const argument = parseUnary();
|
||||
return t.unaryExpression('!', argument);
|
||||
}
|
||||
}
|
||||
return parsePrimary();
|
||||
}
|
||||
|
||||
function parsePrimary() {
|
||||
const token = tokens[i];
|
||||
switch (token.type) {
|
||||
case 'boolean': {
|
||||
i++;
|
||||
return t.booleanLiteral(token.value);
|
||||
}
|
||||
case 'name': {
|
||||
i++;
|
||||
return t.memberExpression(ctxIdentifier, t.identifier(token.name));
|
||||
}
|
||||
case 'string': {
|
||||
i++;
|
||||
return t.stringLiteral(token.value);
|
||||
}
|
||||
case '(': {
|
||||
i++;
|
||||
const expression = parseExpression();
|
||||
const closingParen = tokens[i];
|
||||
if (closingParen === undefined || closingParen.type !== ')') {
|
||||
throw Error('Expected closing )');
|
||||
}
|
||||
i++;
|
||||
return expression;
|
||||
}
|
||||
default: {
|
||||
throw Error('Unexpected token: ' + token.type);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const program = parseExpression();
|
||||
if (tokens[i] !== undefined) {
|
||||
throw Error('Unexpected token');
|
||||
}
|
||||
return program;
|
||||
}
|
||||
|
||||
function buildGateCondition(comments) {
|
||||
let conditions = null;
|
||||
for (const line of comments) {
|
||||
const commentStr = line.value.trim();
|
||||
if (commentStr.startsWith('@gate ')) {
|
||||
const code = commentStr.slice(6);
|
||||
const ctxIdentifier = t.identifier('ctx');
|
||||
const condition = parse(code, ctxIdentifier);
|
||||
if (conditions === null) {
|
||||
conditions = [condition];
|
||||
} else {
|
||||
conditions.push(condition);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (conditions !== null) {
|
||||
let condition = conditions[0];
|
||||
for (let i = 1; i < conditions.length; i++) {
|
||||
const right = conditions[i];
|
||||
condition = t.logicalExpression('&&', condition, right);
|
||||
}
|
||||
return condition;
|
||||
} else {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
name: 'test-gate-pragma',
|
||||
visitor: {
|
||||
ExpressionStatement(path) {
|
||||
const statement = path.node;
|
||||
const expression = statement.expression;
|
||||
if (expression.type === 'CallExpression') {
|
||||
const callee = expression.callee;
|
||||
switch (callee.type) {
|
||||
case 'Identifier': {
|
||||
if (
|
||||
callee.name === 'test' ||
|
||||
callee.name === 'it' ||
|
||||
callee.name === 'fit'
|
||||
) {
|
||||
const comments = statement.leadingComments;
|
||||
if (comments !== undefined) {
|
||||
const condition = buildGateCondition(comments);
|
||||
if (condition !== null) {
|
||||
callee.name =
|
||||
callee.name === 'fit' ? '_test_gate_focus' : '_test_gate';
|
||||
expression.arguments = [
|
||||
t.arrowFunctionExpression(
|
||||
[t.identifier('ctx')],
|
||||
condition
|
||||
),
|
||||
...expression.arguments,
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'MemberExpression': {
|
||||
if (
|
||||
callee.object.type === 'Identifier' &&
|
||||
(callee.object.name === 'test' ||
|
||||
callee.object.name === 'it') &&
|
||||
callee.property.type === 'Identifier' &&
|
||||
callee.property.name === 'only'
|
||||
) {
|
||||
const comments = statement.leadingComments;
|
||||
if (comments !== undefined) {
|
||||
const condition = buildGateCondition(comments);
|
||||
if (condition !== null) {
|
||||
statement.expression = t.callExpression(
|
||||
t.identifier('_test_gate_focus'),
|
||||
[
|
||||
t.arrowFunctionExpression(
|
||||
[t.identifier('ctx')],
|
||||
condition
|
||||
),
|
||||
...expression.arguments,
|
||||
]
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
return;
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = transform;
|
||||
Reference in New Issue
Block a user