blockly 12.3.0 → 12.4.0

package/tests/mocha/test_helpers/block_definitions.js

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function defineEmptyBlock(name = 'empty_block') {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': name,
+      'message0': '',
+    },
+  ]);
+}
+
+export function defineStackBlock(name = 'stack_block') {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': name,
+      'message0': '',
+      'previousStatement': null,
+      'nextStatement': null,
+    },
+  ]);
+}
+
+export function defineRowBlock(name = 'row_block') {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': name,
+      'message0': '%1',
+      'args0': [
+        {
+          'type': 'input_value',
+          'name': 'INPUT',
+        },
+      ],
+      'output': null,
+    },
+  ]);
+}
+
+export function defineRowToStackBlock(name = 'row_to_stack_block') {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': name,
+      'message0': '',
+      'output': null,
+      'nextStatement': null,
+    },
+  ]);
+}
+
+export function defineStatementBlock(name = 'statement_block') {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': name,
+      'message0': '%1',
+      'args0': [
+        {
+          'type': 'input_statement',
+          'name': 'NAME',
+        },
+      ],
+      'previousStatement': null,
+      'nextStatement': null,
+      'colour': 230,
+      'tooltip': '',
+      'helpUrl': '',
+    },
+  ]);
+}
+
+export function defineBasicBlockWithField(name = 'test_field_block') {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': name,
+      'message0': '%1',
+      'args0': [
+        {
+          'type': 'field_input',
+          'name': 'NAME',
+        },
+      ],
+      'output': null,
+    },
+  ]);
+}
+
+export function defineMutatorBlocks() {
+  Blockly.defineBlocksWithJsonArray([
+    {
+      'type': 'xml_block',
+      'mutator': 'xml_mutator',
+    },
+    {
+      'type': 'jso_block',
+      'mutator': 'jso_mutator',
+    },
+    {
+      'type': 'checkbox_block',
+      'message0': '%1',
+      'args0': [
+        {
+          'type': 'field_checkbox',
+          'name': 'CHECK',
+        },
+      ],
+    },
+  ]);
+
+  const xmlMutator = {
+    hasInput: false,
+
+    mutationToDom: function () {
+      const mutation = Blockly.utils.xml.createElement('mutation');
+      mutation.setAttribute('hasInput', this.hasInput);
+      return mutation;
+    },
+
+    domToMutation: function (mutation) {
+      this.hasInput = mutation.getAttribute('hasInput') == 'true';
+      this.updateShape();
+    },
+
+    decompose: function (workspace) {
+      const topBlock = workspace.newBlock('checkbox_block', 'check_block');
+      topBlock.initSvg();
+      topBlock.render();
+      return topBlock;
+    },
+
+    compose: function (topBlock) {
+      this.hasInput = topBlock.getFieldValue('CHECK') == 'TRUE';
+      this.updateShape();
+    },
+
+    updateShape: function () {
+      if (this.hasInput && !this.getInput('INPUT')) {
+        this.appendValueInput('INPUT');
+      } else if (!this.hasInput && this.getInput('INPUT')) {
+        this.removeInput('INPUT');
+      }
+    },
+  };
+  Blockly.Extensions.registerMutator('xml_mutator', xmlMutator);
+
+  const jsoMutator = {
+    hasInput: false,
+
+    saveExtraState: function () {
+      return {hasInput: this.hasInput};
+    },
+
+    loadExtraState: function (state) {
+      this.hasInput = state.hasInput || false;
+      this.updateShape();
+    },
+
+    decompose: function (workspace) {
+      const topBlock = workspace.newBlock('checkbox_block', 'check_block');
+      topBlock.initSvg();
+      topBlock.render();
+      return topBlock;
+    },
+
+    compose: function (topBlock) {
+      this.hasInput = topBlock.getFieldValue('CHECK') == 'TRUE';
+      this.updateShape();
+    },
+
+    updateShape: function () {
+      if (this.hasInput && !this.getInput('INPUT')) {
+        this.appendValueInput('INPUT');
+      } else if (!this.hasInput && this.getInput('INPUT')) {
+        this.removeInput('INPUT');
+      }
+    },
+  };
+  Blockly.Extensions.registerMutator('jso_mutator', jsoMutator);
+}
+
+export function createTestBlock() {
+  return {
+    'id': 'test',
+    'rendered': false,
+    'workspace': {
+      'rendered': false,
+    },
+    'isShadow': function () {
+      return false;
+    },
+    'renameVarById': Blockly.Block.prototype.renameVarById,
+    'updateVarName': Blockly.Block.prototype.updateVarName,
+    'isDeadOrDying': () => false,
+  };
+}
+
+export function createRenderedBlock(workspaceSvg, type) {
+  const block = workspaceSvg.newBlock(type);
+  block.initSvg();
+  block.render();
+  return block;
+}

package/tests/mocha/test_helpers/code_generation.js

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../../node_modules/chai/index.js';
+import {runTestSuites} from './common.js';
+
+/**
+ * Code generation test case configuration.
+ * @implements {TestCase}
+ * @record
+ */
+export class CodeGenerationTestCase {
+  /**
+   * Class for a code generation test case.
+   */
+  constructor() {
+    /**
+     * @type {string} The expected code.
+     */
+    this.expectedCode;
+    /**
+     * @type {boolean|undefined} Whether to use workspaceToCode instead of
+     * blockToCode for test.
+     */
+    this.useWorkspaceToCode;
+    /**
+     * @type {number|undefined} The expected inner order.
+     */
+    this.expectedInnerOrder;
+  }
+
+  /**
+   * Creates the block to use for this test case.
+   * @param {!Blockly.Workspace} workspace The workspace context for this
+   *    test.
+   * @return {!Blockly.Block} The block to use for the test case.
+   */
+  createBlock(workspace) {}
+}
+
+/**
+ * Code generation test suite.
+ * @extends {TestSuite<CodeGenerationTestCase, CodeGenerationTestSuite>}
+ * @record
+ */
+export class CodeGenerationTestSuite {
+  /**
+   * Class for a code generation test suite.
+   */
+  constructor() {
+    /**
+     * @type {!Blockly.CodeGenerator} The generator to use for running test cases.
+     */
+    this.generator;
+  }
+}
+
+/**
+ * Returns mocha test callback for code generation based on provided
+ *    generator.
+ * @param {!Blockly.CodeGenerator} generator The generator to use in test.
+ * @return {function(!CodeGenerationTestCase):!Function} Function that
+ *    returns mocha test callback based on test case.
+ * @private
+ */
+const createCodeGenerationTestFn_ = (generator) => {
+  return (testCase) => {
+    return function () {
+      const block = testCase.createBlock(this.workspace);
+      let code;
+      let innerOrder;
+      if (testCase.useWorkspaceToCode) {
+        code = generator.workspaceToCode(this.workspace);
+      } else {
+        generator.init(this.workspace);
+        code = generator.blockToCode(block);
+        if (Array.isArray(code)) {
+          innerOrder = code[1];
+          code = code[0];
+        }
+      }
+      const assertFunc =
+        typeof testCase.expectedCode === 'string' ? assert.equal : assert.match;
+      assertFunc(code, testCase.expectedCode);
+      if (
+        !testCase.useWorkspaceToCode &&
+        testCase.expectedInnerOrder !== undefined
+      ) {
+        assert.equal(innerOrder, testCase.expectedInnerOrder);
+      }
+    };
+  };
+};
+
+/**
+ * Runs blockToCode test suites.
+ * @param {!Array<!CodeGenerationTestSuite>} testSuites The test suites to run.
+ */
+export const runCodeGenerationTestSuites = (testSuites) => {
+  /**
+   * Creates function used to generate mocha test callback.
+   * @param {!CodeGenerationTestSuite} suiteInfo The test suite information.
+   * @return {function(!CodeGenerationTestCase):!Function} Function that
+   *    creates mocha test callback.
+   */
+  const createTestFn = (suiteInfo) => {
+    return createCodeGenerationTestFn_(suiteInfo.generator);
+  };
+
+  runTestSuites(testSuites, createTestFn);
+};

package/tests/mocha/test_helpers/common.js

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Test case configuration.
+ * @record
+ */
+export class TestCase {
+  /**
+   * Class for a test case configuration.
+   */
+  constructor() {
+    /**
+     * @type {string} The title for the test case.
+     */
+    this.title;
+    /**
+     * @type {boolean|undefined} Whether this test case should be skipped.
+     *   Used to skip buggy test case and should have an associated bug.
+     */
+    this.skip;
+    /**
+     * @type {boolean|undefined} Whether this test case should be called as
+     *   only. Used for debugging.
+     */
+    this.only;
+  }
+}
+
+/**
+ * Test suite configuration.
+ * @record
+ * @template {TestCase} T
+ * @template {TestSuite} U
+ */
+export class TestSuite {
+  /**
+   * Class for a test suite configuration.
+   */
+  constructor() {
+    /**
+     * @type {string} The title for the test case.
+     */
+    this.title;
+    /**
+     * @type {?Array<T>} The associated test cases.
+     */
+    this.testCases;
+    /**
+     * @type {?Array<U>} List of nested inner test suites.
+     */
+    this.testSuites;
+    /**
+     * @type {boolean|undefined} Whether this test suite should be skipped.
+     *   Used to skip buggy test case and should have an associated bug.
+     */
+    this.skip;
+    /**
+     * @type {boolean|undefined} Whether this test suite should be called as
+     *   only. Used for debugging.
+     */
+    this.only;
+  }
+}
+
+/**
+ * Runs provided test cases.
+ * @template {TestCase} T
+ * @param {!Array<T>} testCases The test cases to run.
+ * @param {function(T):Function} createTestCallback Creates test
+ *    callback using given test case.
+ */
+export function runTestCases(testCases, createTestCallback) {
+  testCases.forEach((testCase) => {
+    let testCall = testCase.skip ? test.skip : test;
+    testCall = testCase.only ? test.only : testCall;
+    testCall(testCase.title, createTestCallback(testCase));
+  });
+}
+
+/**
+ * Runs provided test suite.
+ * @template {TestCase} T
+ * @template {TestSuite<T, U>} U
+ * @param {Array<!U>} testSuites The test suites to run.
+ * @param {function(!U):(function(T):!Function)
+ *    } createTestCaseCallback Creates test case callback using given test
+ *    suite.
+ */
+export function runTestSuites(testSuites, createTestCaseCallback) {
+  testSuites.forEach((testSuite) => {
+    let suiteCall = testSuite.skip ? suite.skip : suite;
+    suiteCall = testSuite.only ? suite.only : suiteCall;
+    suiteCall(testSuite.title, function () {
+      if (testSuite.testSuites && testSuite.testSuites.length) {
+        runTestSuites(testSuite.testSuites, createTestCaseCallback);
+      }
+      if (testSuite.testCases && testSuite.testCases.length) {
+        runTestCases(testSuite.testCases, createTestCaseCallback(testSuite));
+      }
+    });
+  });
+}

package/tests/mocha/test_helpers/events.js

@@ -0,0 +1,290 @@
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {assert} from '../../../node_modules/chai/index.js';
+
+/**
+ * Creates spy for workspace fireChangeListener
+ * @param {!Blockly.Workspace} workspace The workspace to spy fireChangeListener
+ *    calls on.
+ * @return {!SinonSpy} The created spy.
+ */
+export function createChangeListenerSpy(workspace) {
+  const spy = sinon.spy();
+  workspace.addChangeListener(spy);
+  return spy;
+}
+
+/**
+ * Creates a mock event for testing if arbitrary events get fired/received.
+ * @param {!Blockly.Workspace} workspace The workspace to create the mock in.
+ * @return {!Object} A mock event that can be fired via Blockly.Events.fire
+ */
+export function createMockEvent(workspace) {
+  return {
+    isNull: () => false,
+    workspaceId: workspace.id,
+  };
+}
+
+/**
+ * Asserts whether the given xml property has the expected property.
+ * @param {!Node} xmlValue The xml value to check.
+ * @param {!Node|string} expectedValue The expected value.
+ * @param {string=} message Optional message to use in assert message.
+ * @private
+ */
+function assertXmlPropertyEqual_(xmlValue, expectedValue, message) {
+  const value = Blockly.Xml.domToText(xmlValue);
+  if (expectedValue instanceof Node) {
+    expectedValue = Blockly.Xml.domToText(expectedValue);
+  }
+  assert.equal(value, expectedValue, message);
+}
+
+/**
+ * Asserts that the given object has the expected xml properties.
+ * @param {Object} obj The object to check.
+ * @param {Object<string, Node|string>} expectedXmlProperties The expected xml
+ *    properties.
+ * @private
+ */
+function assertXmlProperties_(obj, expectedXmlProperties) {
+  Object.keys(expectedXmlProperties).map((key) => {
+    const value = obj[key];
+    const expectedValue = expectedXmlProperties[key];
+    if (expectedValue === undefined) {
+      assert.isUndefined(
+        value,
+        'Expected ' + key + ' property to be undefined',
+      );
+      return;
+    }
+    assert.exists(value, 'Expected ' + key + ' property to exist');
+    assertXmlPropertyEqual_(value, expectedValue, 'Checking property ' + key);
+  });
+}
+
+/**
+ * Whether given key indicates that the property is xml.
+ * @param {string} key The key to check.
+ * @return {boolean} Whether the given key is for xml property.
+ * @private
+ */
+function isXmlProperty_(key) {
+  return key.toLowerCase().endsWith('xml');
+}
+
+/**
+ * Asserts that the given event has the expected values.
+ * @param {!Blockly.Events.Abstract} event The event to check.
+ * @param {string} expectedType Expected type of event fired.
+ * @param {string} expectedWorkspaceId Expected workspace id of event fired.
+ * @param {?string} expectedBlockId Expected block id of event fired.
+ * @param {!Object<string, *>} expectedProperties Map of of additional expected
+ *    properties to check on fired event.
+ * @param {boolean=} [isUiEvent=false] Whether the event is a UI event.
+ * @param {string=} message Optional message to prepend assert messages.
+ */
+export function assertEventEquals(
+  event,
+  expectedType,
+  expectedWorkspaceId,
+  expectedBlockId,
+  expectedProperties,
+  isUiEvent = false,
+  message,
+) {
+  let prependMessage = message ? message + ' ' : '';
+  prependMessage += 'Event fired ';
+  assert.equal(event.type, expectedType, prependMessage + 'type');
+  assert.equal(
+    event.workspaceId,
+    expectedWorkspaceId,
+    prependMessage + 'workspace id',
+  );
+  assert.equal(event.blockId, expectedBlockId, prependMessage + 'block id');
+  Object.keys(expectedProperties).map((key) => {
+    const value = event[key];
+    const expectedValue = expectedProperties[key];
+    if (expectedValue === undefined) {
+      assert.isUndefined(value, prependMessage + key);
+      return;
+    }
+    assert.exists(value, prependMessage + key);
+    if (isXmlProperty_(key)) {
+      assertXmlPropertyEqual_(value, expectedValue, prependMessage + key);
+    } else {
+      assert.equal(value, expectedValue, prependMessage + key);
+    }
+  });
+  if (isUiEvent) {
+    assert.isTrue(event.isUiEvent);
+  } else {
+    assert.isFalse(event.isUiEvent);
+  }
+}
+
+/**
+ * Asserts that an event with the given values was fired.
+ * @param {!SinonSpy|!SinonSpyCall} spy The spy or spy call to use.
+ * @param {function(new:Blockly.Events.Abstract)} instanceType Expected instance
+ *    type of event fired.
+ * @param {!Object<string, *>} expectedProperties Map of of expected properties
+ *    to check on fired event.
+ * @param {string} expectedWorkspaceId Expected workspace id of event fired.
+ * @param {?string=} expectedBlockId Expected block id of event fired.
+ */
+export function assertEventFired(
+  spy,
+  instanceType,
+  expectedProperties,
+  expectedWorkspaceId,
+  expectedBlockId,
+) {
+  const baseProps = {};
+  if (expectedWorkspaceId) baseProps.workspaceId = expectedWorkspaceId;
+  if (expectedBlockId) baseProps.blockId = expectedBlockId;
+  expectedProperties = Object.assign(baseProps, expectedProperties);
+  const expectedEvent = sinon.match
+    .instanceOf(instanceType)
+    .and(sinon.match(expectedProperties));
+  sinon.assert.calledWith(spy, expectedEvent);
+}
+
+/**
+ * Returns a matcher that asserts that the actual object has the same properties
+ * and values (shallowly equated) as the expected object.
+ * @param {!Object} expected The expected set of properties we expect the
+ *    actual object to have.
+ * @return {function(*): boolean} A matcher that returns true if the `actual`
+ *     object has all of the properties of the `expected` param, with the same
+ *     values.
+ */
+function shallowMatch(expected) {
+  return (actual) => {
+    for (const key in expected) {
+      if (actual[key] !== expected[key]) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+/**
+ * Asserts that an event with the given values (shallowly evaluated) was fired.
+ * @param {!SinonSpy|!SinonSpyCall} spy The spy or spy call to use.
+ * @param {function(new:Blockly.Events.Abstract)} instanceType Expected instance
+ *    type of event fired.
+ * @param {!Object<string, *>} expectedProperties Map of of expected properties
+ *    to check on fired event.
+ * @param {string} expectedWorkspaceId Expected workspace id of event fired.
+ * @param {?string=} expectedBlockId Expected block id of event fired.
+ */
+export function assertEventFiredShallow(
+  spy,
+  instanceType,
+  expectedProperties,
+  expectedWorkspaceId,
+  expectedBlockId,
+) {
+  const properties = {
+    ...expectedProperties,
+    workspaceId: expectedWorkspaceId,
+    blockId: expectedBlockId,
+  };
+  sinon.assert.calledWith(
+    spy,
+    sinon.match.instanceOf(instanceType).and(shallowMatch(properties)),
+  );
+}
+
+/**
+ * Asserts that an event with the given values was not fired.
+ * @param {!SpyCall} spy The spy to use.
+ * @param {function(new:Blockly.Events.Abstract)} instanceType Expected instance
+ *    type of event fired.
+ * @param {!Object<string, *>} expectedProperties Map of of expected properties
+ *    to check on fired event.
+ * @param {string=} expectedWorkspaceId Expected workspace id of event fired.
+ * @param {?string=} expectedBlockId Expected block id of event fired.
+ */
+export function assertEventNotFired(
+  spy,
+  instanceType,
+  expectedProperties,
+  expectedWorkspaceId,
+  expectedBlockId,
+) {
+  if (expectedWorkspaceId !== undefined) {
+    expectedProperties.workspaceId = expectedWorkspaceId;
+  }
+  if (expectedBlockId !== undefined) {
+    expectedProperties.blockId = expectedBlockId;
+  }
+  const expectedEvent = sinon.match
+    .instanceOf(instanceType)
+    .and(sinon.match(expectedProperties));
+  sinon.assert.neverCalledWith(spy, expectedEvent);
+}
+
+/**
+ * Filters out xml properties from given object based on key.
+ * @param {Object<string, *>} properties The properties to filter.
+ * @return {Array<Object<string, *>>} A list containing split non
+ *    xml properties and xml properties. [Object<string, *>, Object<string, *>]
+ * @private
+ */
+function splitByXmlProperties_(properties) {
+  const xmlProperties = {};
+  const nonXmlProperties = {};
+  Object.keys(properties).forEach((key) => {
+    if (isXmlProperty_(key)) {
+      xmlProperties[key] = properties[key];
+      return false;
+    } else {
+      nonXmlProperties[key] = properties[key];
+    }
+  });
+  return [nonXmlProperties, xmlProperties];
+}
+
+/**
+ * Asserts that the event passed to the nth call of the given spy has the
+ * expected values. Assumes that the event is passed as the first argument.
+ * @param {!SinonSpy} spy The spy to use.
+ * @param {number} n Which call to check.
+ * @param {function(new:Blockly.Events.Abstract)} instanceType Expected instance
+ *    type of event fired.
+ * @param {Object<string, *>} expectedProperties Map of of expected properties
+ *    to check on fired event.
+ * @param {string} expectedWorkspaceId Expected workspace id of event fired.
+ * @param {?string=} expectedBlockId Expected block id of event fired.
+ */
+export function assertNthCallEventArgEquals(
+  spy,
+  n,
+  instanceType,
+  expectedProperties,
+  expectedWorkspaceId,
+  expectedBlockId,
+) {
+  const nthCall = spy.getCall(n);
+  const splitProperties = splitByXmlProperties_(expectedProperties);
+  const nonXmlProperties = splitProperties[0];
+  const xmlProperties = splitProperties[1];
+
+  assertEventFired(
+    nthCall,
+    instanceType,
+    nonXmlProperties,
+    expectedWorkspaceId,
+    expectedBlockId,
+  );
+  const eventArg = nthCall.firstArg;
+  assertXmlProperties_(eventArg, xmlProperties);
+}