feat: add additional docs and fix input types

Author: kevee

README.md

@@ -118,6 +118,47 @@ const result = await runAirtableScript({
 
 You can pass one of `us`, `friendly`, `european`, or `iso`.
 
+### Mocking fetch requests
+
+Airtable scripts can either use `fetch`, or in extensions `remoteFetchAsync` to make HTTP requests. You can mock these requests using the `fetchMock` setting:
+
+```js
+const result = await runAirtableScript({
+  script: myScript,
+  base: baseFixture,
+  fetchMock: (url, request) => {
+    return {
+      status: 200,
+      body: JSON.stringify({ message: 'Hello, world!' }),
+    }
+  },
+})
+```
+
+### Mocking user inputs
+
+You can mock any `input` from either an automation input or user interaction using the `mockInput` setting:
+
+```js
+const results = await runAirtableScript({
+  script: `
+  const text = await input.textAsync('Select a table')
+  output.inspect(text)
+`,
+  base: randomRecords,
+  mockInput: {
+    // @ts-ignore
+    textAsync: (label) => {
+      if (label === 'Select a table') {
+        return 'text123'
+      }
+    },
+  },
+})
+```
+
+Every [input method for extensions or automations](https://airtable.com/developers/scripting/api/input) are available to be mocked. Check out the [input.test.ts](./test/input.test.ts) file for examples.
+
 ### Results
 
 The results from calling `runAirtableScript` are an object with several properties:

src/environment/console-aggregator.ts

@@ -13,6 +13,9 @@ type ConsoleAggregator = {
 /**
  * Returns a console object that aggregates all messages logged to it.
  * Used to override the global console object in tests.
+ *
+ * The _getMessages method is called after a test is run to pass the
+ * messages to the test runner.
  */
 const consoleAggregator = (): ConsoleAggregator => {
   const consoleMessages: ConsoleMessage[] = []

src/environment/run-airtable-script.ts

@@ -11,6 +11,8 @@ import {
 
 type DefaultDateLocale = 'friendly' | 'us' | 'european' | 'iso'
 
+type Output = [string, number, boolean] | { key: string; value: string }[]
+
 type RunScriptOptions = {
   script: string
   base: { base: unknown } | unknown
@@ -24,7 +26,7 @@ type RunScriptOptions = {
 }
 
 type RunScriptResult = {
-  output: unknown[]
+  output: Output
   mutations: Mutation[]
   console: ConsoleMessage[]
 }
@@ -93,7 +95,7 @@ const runAirtableScript = async ({
   )
 
   return {
-    output: context.__output || [],
+    output: (context.__output as Output) || [],
     mutations: context.__mutations || [],
     console: context.console._getMessages(),
   }

src/environment/sdk/globals/output.ts

@@ -20,12 +20,18 @@ type ExtensionOutput = {
 // @ts-ignore
 globalThis.__output = []
 
+/**
+ * The output object if a script is being used within an automation.
+ */
 const automationOutput: AutomationOutput = {
   set: (key, value) => {
     __output.push({ key, value })
   },
 }
 
+/**
+ * The output object if a script is being used within an extension.
+ */
 const extensionOutput: ExtensionOutput = {
   /**
    * Displays the given text on-screen.
@@ -88,6 +94,7 @@ const extensionOutput: ExtensionOutput = {
   },
 }
 
+// Use one of the two outputs based on the context (extension or automation)
 const output: AutomationOutput | ExtensionOutput = globalThis.__inAutomation
   ? automationOutput
   : extensionOutput

src/environment/sdk/lib/pascal-case.ts

@@ -1,5 +1,6 @@
 /**
- * A pascal case utility function.
+ * A pascal case utility function. Used for schema IDs, which always start with
+ * a three-letter lower-case prefix like tblTableId or fldFieldId.
  */
 const pascalCase = (str: string): string =>
   str

test/input.test.ts

@@ -15,10 +15,12 @@ describe('Input', () => {
           config: () => ({ [key]: 'tbl123' }),
         },
       })
-      expect(results.output[0].key).toEqual('config')
-      expect(results.output[0].value).toEqual(
-        JSON.stringify({ [key]: 'tbl123' })
-      )
+      if (typeof results.output[0] === 'object') {
+        expect(results.output[0].key).toEqual('config')
+        expect(results.output[0].value).toEqual(
+          JSON.stringify({ [key]: 'tbl123' })
+        )
+      }
     })
   })
   describe('extension script', () => {