refresh the readme with recent changes

Author: lopert

README.md

@@ -1,6 +1,6 @@
 # Shopify Functions WASM Testing Helpers
 
-A JavaScript library that rpovides helpers for testing Shopify Functions WASM (WebAssembly) modules. This library provides four core utilities: `loadFixture`, `validateFixture`, `buildFunction`, and `runFunction`.
+A JavaScript library that provides helpers for testing Shopify Functions WASM (WebAssembly) modules. This library provides utilities for loading fixtures, validating test assets, building functions, and running functions.
 
 ## Installation
 
@@ -13,70 +13,258 @@ npm install @shopify/shopify-function-test-helpers
 ### Basic Usage
 
 ```javascript
-const {
+import {
+  buildFunction,
   loadFixture,
-  validateFixture,
+  loadSchema,
+  loadInputQuery,
+  validateTestAssets,
+  runFunction,
+} from "@shopify/shopify-function-test-helpers";
+
+// Load the GraphQL schema and input query
+const schema = await loadSchema("/path/to/schema.graphql");
+const inputQueryAST = await loadInputQuery("/path/to/src/run.graphql");
+
+// Load a test fixture
+const fixture = await loadFixture("/path/to/fixtures/my-test.json");
+
+// Build the function
+await buildFunction("/path/to/function");
+
+// Validate the test assets
+const validationResult = await validateTestAssets({
+  schema,
+  fixture,
+  inputQueryAST,
+});
+
+console.log(`  Input Query: ${validationResult.inputQuery.valid ? '✅' : '❌'}`);
+console.log(`  Input Fixture: ${validationResult.inputFixture.valid ? '✅' : '❌'}`);
+console.log(`  Input Query-Fixture Match: ${validationResult.inputQueryFixtureMatch.valid ? '✅' : '❌'}`);
+console.log(`  Output Fixture: ${validationResult.outputFixture.valid ? '✅' : '❌'}`);
+
+// Run the function
+const runResult = await runFunction(
+  fixture.export,
+  fixture.input,
+  "/path/to/function"
+);
+
+console.log("Output:", runResult.result.output);
+console.log("Expected:", fixture.expectedOutput);
+```
+
+### Complete Test Example
+
+For a full test suite that runs multiple fixtures:
+
+```javascript
+import path from "path";
+import fs from "fs";
+import {
   buildFunction,
-  runFunction
-} = require('@shopify/shopify-function-test-helpers');
+  loadFixture,
+  runFunction,
+  validateTestAssets,
+  loadSchema,
+  loadInputQuery,
+} from "@shopify/shopify-function-test-helpers";
+
+describe("Function Tests", () => {
+  let schema;
+  let inputQueryAST;
+  let functionDir;
+
+  beforeAll(async () => {
+    functionDir = path.dirname(__dirname);
+    await buildFunction(functionDir);
+
+    const schemaPath = path.join(functionDir, "schema.graphql");
+    const inputQueryPath = path.join(functionDir, "src/run.graphql");
+
+    schema = await loadSchema(schemaPath);
+    inputQueryAST = await loadInputQuery(inputQueryPath);
+  }, 10000);
+
+  const fixturesDir = path.join(__dirname, "fixtures");
+  const fixtureFiles = fs
+    .readdirSync(fixturesDir)
+    .filter((file) => file.endsWith(".json"))
+    .map((file) => path.join(fixturesDir, file));
+
+  fixtureFiles.forEach((fixtureFile) => {
+    test(`runs ${path.basename(fixtureFile)}`, async () => {
+      const fixture = await loadFixture(fixtureFile);
+
+      const validationResult = await validateTestAssets({
+        schema,
+        fixture,
+        inputQueryAST,
+      });
+
+      expect(validationResult.inputQuery.valid).toBe(true);
+      expect(validationResult.inputFixture.valid).toBe(true);
+      expect(validationResult.inputQueryFixtureMatch.valid).toBe(true);
+      expect(validationResult.outputFixture.valid).toBe(true);
+
+      const runResult = await runFunction(
+        fixture.export,
+        fixture.input,
+        functionDir
+      );
+
+      expect(runResult.error).toBeNull();
+      expect(runResult.result.output).toEqual(fixture.expectedOutput);
+    }, 10000);
+  });
+});
+```
 
-// Load a fixture from test data
-const fixture = loadFixture('20250915_184036_156Z_extensions_cart-checkout-validation_ba711d.json');
+## API Reference
+
+### Core Functions
+
+#### `loadFixture(fixturePath)`
+
+Loads a fixture file from the specified path.
 
-// Validate the fixture structure
-const validation = validateFixture(fixture);
-console.log('Is valid:', validation.isValid);
+**Parameters:**
+
+- `fixturePath` (string): Path to the fixture JSON file
 
-// Build a function
-const payload = buildFunction();
+**Returns:** Promise<FixtureData> - Fixture object containing `export`, `input`, `expectedOutput`, and `target`
 
-// Run a function implementation
+**Example:**
 
-const result = runFunction(payload, mockFunction);
-console.log('Result status:', result.status);
+```javascript
+const fixture = await loadFixture("./fixtures/my-test.json");
 ```
 
-## API Reference
+---
 
-### Functions
+#### `loadSchema(schemaPath)`
 
-#### `loadFixture(filename)`
-Loads a fixture from the test_data directory.
+Loads a GraphQL schema from a file.
 
 **Parameters:**
-- `filename`: Name of the fixture file
 
-**Returns:** Fixture object
+- `schemaPath` (string): Path to the schema.graphql file
 
-**Throws:** Error if fixture file is not found
+**Returns:** Promise<GraphQLSchema> - Parsed GraphQL schema
 
-#### `validateFixture(fixture)`
-Validates a fixture to ensure it has the correct structure.
+**Example:**
+
+```javascript
+const schema = await loadSchema("./schema.graphql");
+```
+
+---
+
+#### `loadInputQuery(queryPath)`
+
+Loads and parses a GraphQL input query.
 
 **Parameters:**
-- `fixture`: The fixture data to validate
 
-**Returns:** ValidationResult object with `isValid` boolean and `errors` array
+- `queryPath` (string): Path to the GraphQL query file
+
+**Returns:** Promise<DocumentNode> - Parsed GraphQL query AST
+
+**Example:**
+
+```javascript
+const inputQueryAST = await loadInputQuery("./src/run.graphql");
+```
+
+---
+
+#### `validateTestAssets(options)`
+
+Validates test assets including input query, fixture input/output, and query-fixture match.
+
+**Parameters:**
+
+- `options` (ValidateTestAssetsOptions):
+  - `schema` (GraphQLSchema): The GraphQL schema
+  - `fixture` (FixtureData): The fixture to validate
+  - `inputQueryAST` (DocumentNode): The input query AST
+  - `mutationName` (string, optional): The mutation name (auto-detected if not provided)
+  - `resultParameterName` (string, optional): The result parameter name (auto-detected if not provided)
+
+**Returns:** Promise<CompleteValidationResult> - Validation results for all validation steps:
+
+- `inputQuery`: { valid: boolean, errors: readonly GraphQLError[] }
+- `inputFixture`: { valid: boolean, errors: string[], data: any }
+- `inputQueryFixtureMatch`: { valid: boolean, errors: string[] }
+- `outputFixture`: { valid: boolean, errors: { message: string }[], mutationName: string | null, resultParameterType: string | null }
+- `mutationName?`: string - Auto-detected mutation name
+- `resultParameterName?`: string - Auto-detected result parameter name
+- `error?`: string - Top-level error if validation fails
+
+**Example:**
+
+```javascript
+const validationResult = await validateTestAssets({
+  schema,
+  fixture,
+  inputQueryAST,
+});
+
+// Log validation results
+console.log(`  Input Query: ${validationResult.inputQuery.valid ? '✅' : '❌'}`);
+console.log(`  Input Fixture: ${validationResult.inputFixture.valid ? '✅' : '❌'}`);
+console.log(`  Input Query-Fixture Match: ${validationResult.inputQueryFixtureMatch.valid ? '✅' : '❌'}`);
+console.log(`  Output Fixture: ${validationResult.outputFixture.valid ? '✅' : '❌'}`);
+```
+
+---
 
 #### `buildFunction(functionPath?)`
+
 Builds a Shopify function using the Shopify CLI.
 
 **Parameters:**
-- `functionPath` (optional): Path to the function directory. If not provided, will auto-detect from current working directory.
 
-**Returns:** Promise that resolves to build result object with `success`, `output`, and `error` properties.
+- `functionPath` (string, optional): Path to the function directory. If not provided, will auto-detect from current working directory.
+
+**Returns:** Promise<BuildFunctionResult> - Build result with `success`, `output`, and `error` properties
+
+**Example:**
+
+```javascript
+const buildResult = await buildFunction("/path/to/function");
+if (!buildResult.success) {
+  console.error("Build failed:", buildResult.error);
+}
+```
+
+---
 
 #### `runFunction(exportName, input, functionPath?)`
+
 Runs a Shopify function using the Shopify CLI.
 
 **Parameters:**
-- `exportName`: The export name of the function to run
-- `input`: The input data to pass to the function
-- `functionPath` (optional): Path to the function directory. If not provided, will auto-detect from current working directory.
 
-**Returns:** Promise that resolves to result object with `result` and `error` properties.
+- `exportName` (string): The export name of the function to run
+- `input` (object): The input data to pass to the function
+- `functionPath` (string, optional): Path to the function directory. If not provided, will auto-detect from current working directory.
+
+**Returns:** Promise<RunFunctionResult> - Result object with:
+- `result`: { output: any } | null - The function execution result
+- `error`: string | null - Error message if execution failed
+
+**Example:**
+
+```javascript
+const runResult = await runFunction("run", fixtureInput, "/path/to/function");
+console.log("Function output:", runResult.result.output);
+```
+
+**Note:** Both `buildFunction` and `runFunction` will automatically detect the function directory by looking for `shopify.function.toml` in common locations (current directory, src/, functions/, extensions/).
 
-**Note:** Both functions will automatically detect the function directory by looking for `shopify.function.toml` in common locations (current directory, src/, functions/, extensions/). You can also provide a specific path if needed.
+---
 
 ## Development
 
@@ -91,6 +279,15 @@ npm run test:watch
 
 # Run tests with coverage
 npm run test:coverage
+
+# Run example integration tests
+npm run test:examples
+```
+
+### Building
+
+```bash
+npm run build
 ```
 
 ### Linting
@@ -115,7 +312,3 @@ MIT
 4. Add tests for your changes
 5. Run the test suite
 6. Submit a pull request
-
-## Related
-
-- [Tech Design](https://docs.google.com/document/d/1nmJge_seHPgJlzYgux6S90NEVPcYgn9uqimx9AXP_m8/edit?tab=t.0#heading=h.9zotah988fq7)