@baselift/blocks-testing 0.0.1

package/README.md

@@ -0,0 +1,177 @@
+# Introduction to writing automated tests for Airtable Extensions
+
+Support for automated testing is currently in open beta.
+
+## Implementation status
+
+Not all operations are currently supported. In the course of writing tests, authors may find that
+the Extension under test does not function as intended when induced to perform these operations.
+Authors may request support from the SDK maintainers or implement the functionality they need as
+part of their work (this document includes guidance on extending the testing API in a subsequent
+section).
+
+The following table describes the implementation status of each operation.
+
+| operation                 | internal support   | testing API        |
+| ------------------------- | ------------------ | ------------------ |
+| Table - create            | partial [1]        |
+| Table - update            | partial [1]        |
+| Table - destroy           |                    | :heavy_check_mark: |
+| Field - create            | partial [1]        |
+| Field - update            | partial [1]        |
+| Field - destroy           |                    | :heavy_check_mark: |
+| View - create             |                    |
+| View - update             |                    |
+| View - destroy            |                    | :heavy_check_mark: |
+| Global Config - update    | :heavy_check_mark: | n/a [2]            |
+| Cursor Data - update      |                    | :heavy_check_mark: |
+| Session Data - update     |                    |
+| User permissions - update | :heavy_check_mark: | :heavy_check_mark: |
+| click settings button     |                    |
+| toggle full screen        |                    |
+| expand record             |                    | :heavy_check_mark: |  |
+| Record - create           | partial [3]        | n/a [2]            |
+| Record - update           | :heavy_check_mark: | n/a [2]            |
+| Record - destroy          | :heavy_check_mark: | n/a [2]            |
+
+-   [1] While the SDK's public API supports these operations, its capabilities are restricted.
+    Ideally they would be complemented by a more powerful testing API.
+-   [2] These operations can be initiated using the SDK's public API.
+-   [3] Unsupported operations: creating records for tables which have not yet been loaded,
+    [creating records with data for fields which have not yet been loaded](https://github.com/Hyperbase/blocks-sdk/blob/a77fa4b959f512a041e987ee0bfe3fafb7db8b59/packages/sdk/src/models/mutations.ts#L583),
+    and creating records in specific views
+
+## Key concepts
+
+**Test fixture data** is a representation of the state of an Airtable Base, including descriptions
+of Tables, Views, Fields, and Records. It is written by test authors and in terms of
+JSON-serializable values.
+[The Extension Test Fixtures Airtable Extension](https://airtable.com/marketplace/blk5qI32GYyYb1Rbm/test-fixture-generator)
+allows developers to generate this data from the state of an authentic Base. This Extension is not
+ready for beta yet.
+
+**`TestDriver`** is the JavaScript interface for creating and manipulating a simulated Airtable
+Extensions environment. It implements methods for performing operations which are not available in
+the SDK.
+
+**`AirtableInterface`** is the layer of the SDK which mediates between the models and the backend.
+In production environments, it operates via asynchronous message passing with the Extension's parent
+web browser frame. In testing environments, no transmission occurs, but the `AirtableInterface`
+behaves as though it is receiving relevant messages in order to simulate production behavior.
+
+**Mutations** are instructions which describe changes to the Base. Mutations travel through the
+`AirtableInterface`, which sends them to the backend in production environments only.
+
+## Writing tests
+
+As of January 2021, Airtable Extensions must be written using the React framework. These
+instructions take the presence of React for granted.
+
+Every test file must import TestDriver through the `@airtable/blocks-testing` module to ensure that
+the environment is correctly instrumented for automation.
+
+Each test will typically perform the following steps:
+
+1.  Create a TestDriver instance, providing valid fixture data:
+
+    ```js
+    const testDriver = new TestDriver({
+        /* fixture data here */
+    });
+    ```
+
+2.  Create an instance of the Extension under test by rendering the Extension's Component as a child
+    of the `TestDriver#Container` Component.
+
+    ```js
+    render(
+        <testDriver.Container>
+            <MyExtension />
+        </testDriver.Container>,
+    );
+    ```
+
+3.  Provide some input to the Extension. This may be in the form of a simulated user interaction
+    (e.g. via
+    [the `@testing-library/user-event` library](https://www.npmjs.com/package/@testing-library/user-event))
+
+    ```js
+    // Simulate a user choosing the "Gruyere" option from the table labed
+    // "Cheeses".
+    const input = screen.getByLabelText('Cheeses');
+    const option = screen.getByText('Gruyere');
+    userEvent.selectOptions(input, [option]);
+    ```
+
+    ...or a simulated backend behavior (e.g. via
+    [the Blocks SDK](https://airtable.com/developers/apps) or the `TestDriver` API).
+
+    ```js
+    // Invoking `createTableAsync` in a test script simulates the condition
+    // where the Airtable backend reports that a table has been created by
+    // another viewer of the Base.
+    await testDriver.base.createTableAsync('a new table', [
+        {name: 'address', type: FieldType.EMAIL},
+    ]);
+    ```
+
+4.  Verify that the Extension responded to the input as expected. For many kinds of interactions,
+    the Extension's response will be discernible by some change in the UI.
+    [The `@testing-library/react` library](https://www.npmjs.com/package/@testing-library/react) is
+    a good choice for inspecting the state of the user interface.
+
+    ```js
+    // Ensure that the UI updated to display the checkbox as "checked"
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox.checked).toBe(true);
+    ```
+
+    ...while the `TestDriver` API can be used to verify Extension behaviors which do not influence
+    the UI:
+
+    ```js
+    // Track every time the Extension attempts to expand a record.
+    const recordIds = [];
+    testDriver.watch('expandRecord', ({recordId}) => recordIds.push(recordId));
+
+    // (The code necessary to simulate user inteaction elided from this example.)
+
+    // Ensure that the Extension attempted to expand the Record with ID `reca`
+    expect(recordIds).toEqual(['reca']);
+    ```
+
+[The automated test suite for the To-do List example Extension](https://github.com/Airtable/apps-todo-list/tree/master/test)
+demonstrates this pattern.
+
+## Extending the Testing API
+
+In order to provide predictable behavior, the Airtable testing platform relies on simulations of
+Base operations. Every simulation requires some amount of support in the testing platform. Some
+simulations also require a dedicated testing API.
+
+**Implementing internal support** Every Base operation requires some amount of simulation code in
+order to support scripting in test environments.
+
+For some operations, this simulation may be as limited as a "no-op" implementation of an internal
+method. These operations include mutations which the SDK applies optimistically and messages with no
+direct effect on the Extension.
+
+Other operations will require more advanced simulation logic. Operations of this type generally rely
+on the backend's response to determine their effect on the Base. The simulated behavior should be
+predictable, mimicking the expected response in production.
+
+**Implementing a dedicated API** A dedicated testing API is not necessary for any operation which
+can be expressed through the public API of the SDK (e.g. "create many records" or "delete a table").
+When a test author wishes to script such an operation, they should use the SDK directly. This is
+valid because an Extension cannot distinguish between operations initiated by the backend and
+operations initiated by a test script using the SDK.
+
+Many other operations cannot be expressed via the public API of the SDK. The `TestDriver` API must
+be extended to allow test authors to simulate these operations.
+
+Some of these restrictions are circumstantial, owing to the fact that as of January 2021, the SDK is
+incomplete and under active development. This includes an API to delete a Field. Other restrictions
+are fundamental to the design of the Extensions platform. For instance, the SDK intentionally omits
+a method for an Extension to change the permissions of the current user. This distinction may inform
+the decision to introduce a testing API, since doing so will increase maintenance responsibilities
+in a way that may be obviated by future extensions to the SDK's public API.

package/dist/cjs/error_utils.js

@@ -0,0 +1,56 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.invariant = invariant;
+exports.spawnError = spawnError;
+require("core-js/modules/es.regexp.exec.js");
+require("core-js/modules/es.string.replace.js");
+/**
+ * @internal
+ */
+function spawnErrorWithOriginOmittedFromStackTrace(errorMessageFormat, errorMessageArgs, errorOriginFn) {
+  var safeMessage = errorMessageFormat;
+  var argIndex = 0;
+  var formattedMessage = errorMessageFormat.replace(/%s/g, () => {
+    var arg = errorMessageArgs ? errorMessageArgs[argIndex] : undefined;
+    argIndex++;
+    return String(arg);
+  });
+  var err = new Error(formattedMessage);
+  if (Error.captureStackTrace && errorOriginFn) {
+    Error.captureStackTrace(err, errorOriginFn);
+  }
+  Object.defineProperty(err, '__safeMessage', {
+    configurable: false,
+    enumerable: false,
+    value: safeMessage,
+    writable: false
+  });
+  return err;
+}
+
+/**
+ * @hidden
+ */
+function spawnError(errorMessageFormat) {
+  for (var _len = arguments.length, errorMessageArgs = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    errorMessageArgs[_key - 1] = arguments[_key];
+  }
+  return spawnErrorWithOriginOmittedFromStackTrace(errorMessageFormat, errorMessageArgs, spawnError);
+}
+
+/**
+ * An alternative to facebook's invariant that's safe to use with base data
+ *
+ * @hidden
+ */
+function invariant(condition, errorMessageFormat) {
+  if (!condition) {
+    for (var _len2 = arguments.length, errorMessageArgs = new Array(_len2 > 2 ? _len2 - 2 : 0), _key2 = 2; _key2 < _len2; _key2++) {
+      errorMessageArgs[_key2 - 2] = arguments[_key2];
+    }
+    throw spawnErrorWithOriginOmittedFromStackTrace(errorMessageFormat, errorMessageArgs, invariant);
+  }
+}

package/dist/cjs/index.js

@@ -0,0 +1,24 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "MutationTypes", {
+  enumerable: true,
+  get: function get() {
+    return _unstable_testing_utils.MutationTypes;
+  }
+});
+Object.defineProperty(exports, "default", {
+  enumerable: true,
+  get: function get() {
+    return _test_driver.default;
+  }
+});
+var _unstable_testing_utils = require("@baselift/blocks/unstable_testing_utils");
+var _semver = _interopRequireDefault(require("semver"));
+require("./inject_mock_airtable_interface");
+var _error_utils = require("./error_utils");
+var _test_driver = _interopRequireDefault(require("./test_driver"));
+(0, _error_utils.invariant)(_semver.default.satisfies(_unstable_testing_utils.Sdk.VERSION, "^1.2.2"), 'Version %s of the blocks-testing library does not support version %s of the Blocks SDK library.', "0.0.1", _unstable_testing_utils.Sdk.VERSION);

package/dist/cjs/inject_mock_airtable_interface.js

@@ -0,0 +1,6 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _vacant_airtable_interface = _interopRequireDefault(require("./vacant_airtable_interface"));
+var vacantAirtableInterface = new _vacant_airtable_interface.default();
+window.__getAirtableInterfaceAtVersion = () => vacantAirtableInterface;