@gsb-core/mcp-docs/src/docs/testWfFunction.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the testWfFunction operation
 */

/**
 * Returns documentation for the testWfFunction operation
 * @return {string} markdown documentation
 */
export function testWfFunctionDocs(): string {
  return `
# TestWfFunction Operation

## General Description

The \`testWfFunction\` operation allows you to test a workflow function without saving it to the GSB backend.

## Detailed Description

The \`testWfFunction\` operation is a powerful tool for developing and testing GSB serverless functions. It executes the provided function code with the specified context (entity and parameters) and returns the result, but does not persist the function definition to the GSB backend. This makes it ideal for:

- Developing and debugging new functions
- Testing function behavior with different inputs
- Validating function logic before deployment
- Experimenting with function modifications

You can provide both the function code directly and an execution context with entity and parameters, allowing for comprehensive testing of function behavior.

## Input Parameters

The \`testWfFunction\` operation accepts a request object with the following structure:

\`\`\`javascript
{
  "function": {
    // Required: Function details
    "name": "myFunction", // Name for the function (for reference only)
    "code": "// JavaScript code for the function\n_runtime.success('Success', {result: _instance.entity?.a + _instance.prms?.b});",
    // Optional: Operations array as a JSON string
    "operations": "[{...operation objects...}]"
  },
  "instance": {
    // Optional: Entity context to pass to the function
    "entity": {
      // Entity data properties
      "a": 1
    },
    // Optional: Parameters to pass to the function
    "prms": {
      "b": 2
    }
  }
}
\`\`\`

### Key Parameters:

- **function.name**: A name for the function (for reference only, not saved)
- **function.code**: The JavaScript code for the function to test
- **function.operations**: Optional JSON string containing declarative operations
- **instance.entity**: Optional entity object to pass as \`_instance.entity\` to the function
- **instance.prms**: Optional parameters object to pass as \`_instance.prms\` to the function

## Response

The response from \`testWfFunction\` contains:

1. The function's execution result, including:
   - Whatever was set by \`_runtime.success()\`, \`_runtime.error()\`, or \`_runtime.end()\`
   - Any values assigned to \`_instance.response\`

2. Status information and execution details

Example response structure:
\`\`\`javascript
{
  "response": {
    // Data returned by the function
    "ret": 3 // Example: result of _instance.entity.a + _instance.prms.b
  },
  "status": 200,
  "message": "success"
}
\`\`\`

## Example Usage

### Example 1: Testing a Simple Function

\`\`\`javascript
// Request to test a simple calculation function
let testRequest = {
  "function": {
    "name": "addValues",
    "code": "let result = _instance.entity.value1 + _instance.prms.value2;\n_runtime.success('Calculation complete', {sum: result});"
  },
  "instance": {
    "entity": {
      "value1": 10
    },
    "prms": {
      "value2": 20
    }
  }
};

// Using GsbEntityService to test the function
let entityService = new GsbEntityService(_runtime);
let testResult = await entityService.testWfFunction(testRequest);

// testResult.response would contain {sum: 30}
\`\`\`

### Example 2: Testing a Function with Error Handling

\`\`\`javascript
// Request to test a function with validation and error handling
let testRequest = {
  "function": {
    "name": "validateOrder",
    "code": \`
      // Get order from entity context
      let order = _instance.entity;
      
      // Validate required fields
      let errors = [];
      if (!order.customer_id) errors.push("Customer is required");
      if (!order.items || order.items.length === 0) errors.push("Order must have at least one item");
      
      // Return validation result
      if (errors.length > 0) {
        _runtime.error("Validation failed", {errors: errors});
      } else {
        _runtime.success("Validation passed");
      }
    \`
  },
  "instance": {
    "entity": {
      "id": "order123",
      "customer_id": "", // Invalid - empty customer ID
      "items": [] // Invalid - empty items array
    }
  }
};

// Test the function
let testResult = await entityService.testWfFunction(testRequest);

// testResult would contain validation errors
\`\`\`

### Example 3: Testing a Function with Declarative Operations

\`\`\`javascript
// Request to test a function with both code and operations
let testRequest = {
  "function": {
    "name": "processOrder",
    "code": "// Custom pre-processing code\nlet order = _instance.entity;\norder.preprocessed = true;",
    "operations": "[{\\"id\\":\\"op1\\",\\"orderNumber\\":1,\\"operationType\\":10,\\"title\\":\\"Set Order Status\\",\\"setEntityOptions\\":{\\"setProps\\":[{\\"name\\":\\"status\\",\\"value\\":2}]}}]"
  },
  "instance": {
    "entity": {
      "id": "order456",
      "status": 1
    }
  }
};

// Test the function
let testResult = await entityService.testWfFunction(testRequest);
\`\`\`

## Additional Information

### Best Practices for Testing Functions

1. **Incremental Testing**: Start with simple test cases and gradually add complexity.

2. **Test Edge Cases**: Include tests for boundary conditions, invalid inputs, and error scenarios.

3. **Isolate Dependencies**: When testing functions that call other functions or services, consider mocking those dependencies in your test code.

4. **Comprehensive Validation**: Check both the happy path (successful execution) and error paths.

5. **From Test to Production**: Once a function passes testing, you can save it to the GSB backend using \`GsbEntityService.save()\` with \`entDefName: "GsbWfFunction"\`.

### Converting Test Functions to Production

After successful testing, you can save the function to the GSB backend:

\`\`\`javascript
// Save the tested function to the backend
let saveRequest = {
  "entDefName": "GsbWfFunction",
  "entity": {
    "name": "myFunction", // Required
    "title": "My Function", // Required
    "code": "// The function code that was tested",
    "operations": "[{...operations that were tested...}]"
  }
};

let saveResult = await entityService.save(saveRequest);
let savedFunctionId = saveResult.id;
\`\`\`

### Testing vs. Running Functions

- **testWfFunction**: Tests function code without saving it to the backend
- **runWfFunction**: Executes a function that's already saved in the backend
- **saveEnt with GsbWfFunction**: Saves a function to the backend for later use
`;
}

/**
 * Returns a brief summary of the testWfFunction operation.
 * @return {string} A short description of the function.
 */
export function testWfFunctionSummary(): string {
  return `
**Purpose**: Tests a workflow function without saving it to the GSB backend.

**When to use**:
- Developing and debugging new functions
- Testing function behavior with different inputs
- Validating function logic before deployment
- Experimenting with function modifications

**Key features**:
- Execute function code without persistence
- Test with custom entity and parameter contexts
- Validate both code and declarative operations
- Receive full execution results for verification
`;
}

export default testWfFunctionDocs;