ApiLogicServer 15.1.2__py3-none-any.whl → 15.2.0__py3-none-any.whl

api_logic_server_cli/prototypes/base/test/api_logic_server_behave/check_step_order.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Verify Behave step ordering for multi-param patterns.
+
+Usage:
+    cd test/api_logic_server_behave
+    python check_step_order.py
+
+This script checks if Behave step patterns are ordered from most specific
+to most general, preventing Rule #0.5 violations that cause silent test failures.
+
+Rule #0.5: Behave matches steps by FIRST pattern that fits.
+More specific patterns MUST come before general ones.
+"""
+import re
+import sys
+from pathlib import Path
+
+
+def check_step_order(steps_file):
+    """
+    Check if multi-item patterns come before single-item patterns.
+    
+    Returns list of issues found, or empty list if order is correct.
+    """
+    with open(steps_file) as f:
+        lines = f.readlines()
+    
+    issues = []
+    when_patterns = []
+    
+    for i, line in enumerate(lines, 1):
+        # Look for @when patterns with parameters
+        if match := re.match(r"@when\('.*with.*\{", line):
+            # Calculate specificity score
+            param_count = line.count('{')  # More parameters = more specific
+            has_and = ' and ' in line  # "and" keyword = multi-item pattern
+            
+            # Check for special keywords that make patterns more specific
+            special_keywords = ['carbon neutral', 'shipped', 'unshipped']
+            has_special_keyword = any(k in line for k in special_keywords)
+            
+            # Specificity score: higher = more specific
+            specificity = param_count + (2 if has_and else 0) + (3 if has_special_keyword else 0)
+            
+            when_patterns.append((i, specificity, line.strip()))
+    
+    # Check if patterns are in descending specificity order
+    for i in range(len(when_patterns) - 1):
+        curr_line, curr_spec, curr_text = when_patterns[i]
+        next_line, next_spec, next_text = when_patterns[i + 1]
+        
+        # Check if patterns are mutually exclusive (both have unique keywords)
+        curr_has_unique = any(k in curr_text for k in ['carbon neutral', 'shipped'])
+        next_has_unique = any(k in next_text for k in [' and '])
+        mutually_exclusive = curr_has_unique and next_has_unique
+        
+        # If next pattern is MORE specific than current AND not mutually exclusive
+        if next_spec > curr_spec and not mutually_exclusive:
+            issues.append(f"❌ Line {next_line} (specificity={next_spec}) should come BEFORE line {curr_line} (specificity={curr_spec})")
+            issues.append(f"   More specific: {next_text}")
+            issues.append(f"   Less specific: {curr_text}")
+            issues.append(f"   FIX: Move line {next_line} to BEFORE line {curr_line}")
+        
+        # CRITICAL CHECK: Multi-item must come before single-item (same base pattern)
+        curr_has_and = ' and ' in curr_text
+        next_has_and = ' and ' in next_text
+        curr_param_count = curr_text.count('{')
+        next_param_count = next_text.count('{')
+        
+        # If current is single-item (2 params, no 'and') and next is multi-item (4+ params, has 'and')
+        if (not curr_has_and and curr_param_count == 2 and 
+            next_has_and and next_param_count >= 4):
+            issues.append(f"❌ CRITICAL: Line {next_line} (multi-item) MUST come BEFORE line {curr_line} (single-item)")
+            issues.append(f"   This causes silent failures: orders not created, balance=0")
+            issues.append(f"   Multi-item: {next_text}")
+            issues.append(f"   Single-item: {curr_text}")
+            issues.append(f"   FIX: Move line {next_line} to BEFORE line {curr_line}")
+    
+    return issues
+
+
+def main():
+    """Check all step files in features/steps directory."""
+    steps_dir = Path('features/steps')
+    
+    if not steps_dir.exists():
+        print(f"❌ Directory not found: {steps_dir}")
+        print("   Run this script from: test/api_logic_server_behave/")
+        sys.exit(1)
+    
+    all_issues = []
+    files_checked = 0
+    
+    for steps_file in steps_dir.glob('*_steps.py'):
+        files_checked += 1
+        issues = check_step_order(steps_file)
+        if issues:
+            all_issues.extend([f"\n📁 {steps_file}:"] + issues)
+    
+    if all_issues:
+        print("=" * 70)
+        print("Step Ordering Issues Found (Rule #0.5 Violation)")
+        print("=" * 70)
+        print('\n'.join(all_issues))
+        print("\n" + "=" * 70)
+        print("IMPACT: Tests may pass but produce wrong results (e.g., balance=0)")
+        print("ACTION: Reorder @when patterns from most→least specific")
+        print("=" * 70)
+        sys.exit(1)
+    else:
+        print("=" * 70)
+        print(f"✅ All step patterns correctly ordered ({files_checked} files checked)")
+        print("   Rule #0.5: Most specific → Most general ✓")
+        print("=" * 70)
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

api_logic_server_cli/prototypes/base/test/api_logic_server_behave/features/steps/test_data_helpers.py

@@ -0,0 +1,242 @@
+"""
+Test Data Helpers - Query or Create Test Data
+
+These helpers ensure tests work with any database state by:
+1. Querying existing data when available
+2. Creating test data programmatically when needed
+3. Using correct data types (Integer IDs, not strings)
+
+Usage:
+    customer_id = get_or_create_test_customer(balance=0, credit_limit=1000)
+    product_id = get_or_create_test_product(unit_price=5.00)
+"""
+
+import requests
+import json
+import test_utils
+from decimal import Decimal
+import time
+
+
+def get_or_create_test_customer(name: str = "Test Customer", 
+                                balance: float = 0, 
+                                credit_limit: float = 1000) -> int:
+    """
+    Create a NEW test customer (always creates, never reuses).
+    
+    IMPORTANT: balance is a derived aggregate (sum of unshipped orders).
+    - If balance=0: Just create customer (aggregates default to 0)
+    - If balance>0: Must be created by caller via orders/items (see note below)
+    
+    NOTE: This function does NOT create filler orders to reach target balance.
+    If you need balance > 0, the caller must create orders/items after getting customer_id.
+    
+    Returns INTEGER customer ID (not string!)
+    
+    Args:
+        name: Customer name (timestamp added to ensure uniqueness)
+        balance: Target balance (for documentation - NOT enforced by this function)
+        credit_limit: Credit limit
+        
+    Returns:
+        int: Customer ID (e.g., 1, not 'CUST-1')
+    """
+    # Always create NEW customer (add timestamp to name for uniqueness)
+    unique_name = f"{name} {int(time.time() * 1000)}"  # Add millisecond timestamp
+    
+    post_uri = 'http://localhost:5656/api/Customer/'
+    post_data = {
+        "data": {
+            "attributes": {
+                "name": unique_name,
+                # NOTE: Do NOT set balance here - it's a derived aggregate!
+                "credit_limit": credit_limit
+            },
+            "type": "Customer"
+        }
+    }
+    r = requests.post(url=post_uri, json=post_data, headers=test_utils.login())
+    result = json.loads(r.text)
+    return int(result['data']['id'])  # Convert to int!
+
+
+def get_or_create_test_product(name: str = "Test Product", 
+                               unit_price: float = 5.00) -> int:
+    """
+    Get or create a test product with specified attributes.
+    
+    Returns INTEGER product ID (not string!)
+    
+    Args:
+        name: Product name
+        unit_price: Unit price
+        
+    Returns:
+        int: Product ID (e.g., 1, not 'PROD-A')
+    """
+    # Try to find existing product
+    get_uri = f'http://localhost:5656/api/Product/?filter[name]={name}'
+    r = requests.get(url=get_uri, headers=test_utils.login())
+    data = json.loads(r.text)
+    
+    if data.get('data') and len(data['data']) > 0:
+        product_id = int(data['data'][0]['id'])  # Convert to int!
+        # Update to ensure correct price
+        patch_uri = f'http://localhost:5656/api/Product/{product_id}/'
+        patch_data = {
+            "data": {
+                "attributes": {"unit_price": unit_price},
+                "type": "Product",
+                "id": product_id
+            }
+        }
+        requests.patch(url=patch_uri, json=patch_data, headers=test_utils.login())
+        return product_id
+    else:
+        # Create new product
+        post_uri = 'http://localhost:5656/api/Product/'
+        post_data = {
+            "data": {
+                "attributes": {
+                    "name": name,
+                    "unit_price": unit_price
+                },
+                "type": "Product"
+            }
+        }
+        r = requests.post(url=post_uri, json=post_data, headers=test_utils.login())
+        result = json.loads(r.text)
+        return int(result['data']['id'])  # Convert to int!
+
+
+def create_test_order(customer_id: int, notes: str = "Test Order") -> int:
+    """
+    Create a test order (always creates new, doesn't reuse).
+    
+    Args:
+        customer_id: INTEGER customer ID
+        notes: Order notes
+        
+    Returns:
+        int: Order ID
+    """
+    post_uri = 'http://localhost:5656/api/Order/'
+    post_data = {
+        "data": {
+            "attributes": {
+                "customer_id": customer_id,  # Integer, not string!
+                "notes": notes,
+                "date_shipped": None  # Unshipped
+            },
+            "type": "Order"
+        }
+    }
+    r = requests.post(url=post_uri, json=post_data, headers=test_utils.login())
+    result = json.loads(r.text)
+    return int(result['data']['id'])  # Convert to int!
+
+
+def create_test_item(order_id: int, product_id: int, quantity: int = 10) -> int:
+    """
+    Create a test order item.
+    
+    Args:
+        order_id: INTEGER order ID
+        product_id: INTEGER product ID
+        quantity: Quantity
+        
+    Returns:
+        int: Item ID
+    """
+    post_uri = 'http://localhost:5656/api/Item/'
+    post_data = {
+        "data": {
+            "attributes": {
+                "order_id": order_id,      # Integer!
+                "product_id": product_id,  # Integer!
+                "quantity": quantity
+            },
+            "type": "Item"
+        }
+    }
+    r = requests.post(url=post_uri, json=post_data, headers=test_utils.login())
+    result = json.loads(r.text)
+    if r.status_code > 300 or 'data' not in result:
+        raise Exception(f"Failed to create item: {r.status_code} - {r.text}")
+    return int(result['data']['id'])  # Convert to int!
+
+
+def delete_test_data(customer_id: int = None, order_id: int = None, item_id: int = None):
+    """
+    Clean up test data (use in teardown or when resetting state).
+    
+    Args:
+        customer_id: Customer to delete
+        order_id: Order to delete  
+        item_id: Item to delete
+    """
+    if item_id:
+        delete_uri = f'http://localhost:5656/api/Item/{item_id}/'
+        requests.delete(url=delete_uri, headers=test_utils.login())
+    
+    if order_id:
+        delete_uri = f'http://localhost:5656/api/Order/{order_id}/'
+        requests.delete(url=delete_uri, headers=test_utils.login())
+    
+    if customer_id:
+        delete_uri = f'http://localhost:5656/api/Customer/{customer_id}/'
+        requests.delete(url=delete_uri, headers=test_utils.login())
+
+
+def get_customer(customer_id: int) -> dict:
+    """
+    Fetch customer data by INTEGER ID.
+    
+    Args:
+        customer_id: INTEGER customer ID (e.g., 1, not 'CUST-1')
+        
+    Returns:
+        dict: Customer attributes (id, name, balance, credit_limit, etc.)
+    """
+    get_uri = f'http://localhost:5656/api/Customer/{customer_id}/'
+    r = requests.get(url=get_uri, headers=test_utils.login())
+    if r.status_code > 300:
+        raise Exception(f'get_customer failed with {r.text}')
+    result_data = json.loads(r.text)
+    return result_data['data']['attributes']
+
+
+def get_order(order_id: int) -> dict:
+    """
+    Fetch order data by INTEGER ID.
+    
+    Args:
+        order_id: INTEGER order ID
+        
+    Returns:
+        dict: Order attributes
+    """
+    get_uri = f'http://localhost:5656/api/Order/{order_id}/'
+    r = requests.get(url=get_uri, headers=test_utils.login())
+    if r.status_code > 300:
+        raise Exception(f'get_order failed with {r.text}')
+    result_data = json.loads(r.text)
+    return result_data['data']['attributes']
+
+
+def get_item(item_id: int) -> dict:
+    """
+    Fetch item data by INTEGER ID.
+    
+    Args:
+        item_id: INTEGER item ID
+        
+    Returns:
+        dict: Item attributes
+    """
+    get_uri = f'http://localhost:5656/api/Item/{item_id}/'
+    r = requests.get(url=get_uri, headers=test_utils.login())
+    if r.status_code > 300:
+        raise Exception(f'get_item failed with {r.text}')
+    result_data = json.loads(r.text)
+    return result_data['data']['attributes']

api_logic_server_cli/prototypes/base/test/api_logic_server_behave/features/steps/test_utils.py

@@ -3,6 +3,7 @@ import json
 from dotmap import DotMap
 import sys, os
 from pathlib import Path
+from urllib.parse import quote
 
 __version__ = '0.0.1'  # keycloak support
 
@@ -29,7 +30,10 @@ def prt(msg: any, test: str= None) -> None:
         test_val = test[0:25]
     if "Server Log: Behave Run Successfully Completed" in msg:
         debug_stop = 'good breakpoint'
-    msg_url = f'http://localhost:5656/server_log?msg={msg}&test={test}&dir=test/api_logic_server_behave/logs/scenario_logic_logs'
+    # URL-encode msg and test to handle special characters, newlines, spaces, etc.
+    msg_encoded = quote(str(msg))
+    test_encoded = quote(str(test)) if test else 'None'
+    msg_url = f'http://localhost:5656/server_log?msg={msg_encoded}&test={test_encoded}&dir=test/api_logic_server_behave/logs/scenario_logic_logs'
     r = requests.get(msg_url)
 
 

api_logic_server_cli/prototypes/base/test/api_logic_server_behave/reports/Behave Logic Report Intro micro.md

@@ -1,4 +1,19 @@
+This report shows test results with embedded logic execution traces.
+
+**For complete documentation on using Behave:** See [Behave.md](https://apilogicserver.github.io/Docs/Behave/)
+
+**About This Project:**
+
+_**TODO:** [Describe your project here - what it does, key features tested, etc.]_
+
+ 
+
 This report combines:
+
 * Behave log (lists Features, test Scenarios, results), with embedded
 * Logic showing rules executed, and how they operated
 
+---
+
+# Behave Logic Report
+

api_logic_server_cli/prototypes/base/test/api_logic_server_behave/reports/Behave Logic Report Intro.md

@@ -1,75 +1,19 @@
-# Behave Creates Executable Test Suite, Documentation
+This report shows test results with embedded logic execution traces.
 
-You can optionally use the Behave test framework to:
+**For complete documentation on using Behave:** See [Behave.md](https://apilogicserver.github.io/Docs/Behave/)
 
-1. **Create and Run an Executable Test Suite:** in your IDE, create test definitions (similar to what is shown in the report below), and Python code to execute tests.  You can then execute your test suite with 1 command.
+**About This Project:**
 
-2. **Requirements and Test Documentation:** as shown below, you can then create a wiki report that documents your requirements, and the tests (**Scenarios**) that confirm their proper operation.
+_**TODO:** [Describe your project here - what it does, key features tested, etc.]_
 
-   * **Logic Documentation:** the report integrates your logic, including a logic report showing your logic (rules and Python), and a Logic Log that shows exactly how the rules executed.  Logic Doc can further contribute to Agile Collaboration.
+ 
 
-<figure><img src="https://raw.githubusercontent.com/ApiLogicServer/Docs/main/docs/images/behave/behave-summary.png"  height="600"></figure>
+This report combines:
 
+* Behave log (lists Features, test Scenarios, results), with embedded
+* Logic showing rules executed, and how they operated
 
+---
 
-[Behave](https://behave.readthedocs.io/en/stable/tutorial.html) is a framework for defining and executing tests.  It is based on [TDD (Test Driven Development)](http://dannorth.net/introducing-bdd/), an Agile approach for defining system requirements as executable tests.
+# Behave Logic Report
 
-&nbsp;&nbsp;
-
-# Using Behave
-
-<figure><img src="https://raw.githubusercontent.com/ApiLogicServer/Docs/main/docs/images/behave/TDD-ide.png?raw=true"></figure>
-
-Behave is pre-installed with API Logic Server.  Use it as shown above:
-
-1. Create `.feature` files to define ***Scenarios*** (aka tests) for ***Features*** (aka Stories)
-
-2. Code `.py` files to implement Scenario tests
-
-3. Run Test Suite: Launch Configuration `Behave Run`.  This runs all your Scenarios, and produces a summary report of your Features and the test results.
-
-4. Report: Launch Configuration `Behave Report` to create the wiki file shown at the top of this page.
-
-These steps are further defined, below.  Explore the samples in the sample project.
-
-&nbsp;&nbsp;
-
-## 1. Create `.feature` file to define Scenario
-
-Feature (aka Story) files are designed to promote IT / business user collaboration.  
-
-&nbsp;&nbsp;
-
-## 2. Code `.py` file to implement test
-
-Implement your tests in Python.  Here, the tests are largely _read existing data_, _run transaction_, and _test results_, using the API.  You can obtain the URLs from the swagger.
-
-Key points:
-
-* Link your scenario / implementations with annotations, as shown for _Order Placed with excessive quantity_.
-
-* Include the `test_utils.prt()` call; be sure to use specify the scenario name as the 2nd argument.  This is what drives the name of the Logic Log file, discussed below.
-
-* Optionally, include a Python docstring on your `when` implementation as shown above, delimited by `"""` strings (see _"Familiar logic pattern"_ in the screen shot, above). If provided, this will be written into the wiki report.
-
-* Important: the system assumes the following line identifies the scenario_name; be sure to include it.
-
-&nbsp;&nbsp;
-
-## 3. Run Test Suite: Launch Configuration `Behave Run`
-
-You can now execute your Test Suite.  Run the `Behave Run` Launch Configuration, and Behave will run all of the tests, producing the outputs (`behave.log` and `<scenario.logs>` shown above.
-
-* Windows users will need to run `Windows Behave Run`
-
-* You can run just 1 scenario using `Behave Scenario`
-
-* You can set breakpoints in your tests
-
-The server must be running for these tests.  Use the Launch Configuration `ApiLogicServer`, or `python api_logic_server_run.py`.  The latter does not run the debugger, which you may find more convenient since changes to your test code won't restart the server.
-
-&nbsp;&nbsp;
-
-## 4. Report: Launch Configuration `Behave Report'
-
-Run this to create the wiki reports from the logs in step 3.

api_logic_server_cli/prototypes/base/test/readme_test.md

@@ -49,6 +49,26 @@ python behave_run.py
 # In Debug Console, select "Behave Run" from dropdown (not server log)
 ```
 
+### Running Specific Tests
+
+You can run specific features or scenarios using behave's command-line options:
+
+```bash
+# Run a specific feature file
+behave features/check_credit.feature
+
+# Run a specific scenario by name
+behave -n "Good Order - Basic Chain"
+
+# Run scenarios matching a pattern
+behave -n ".*credit.*"
+
+# Run with tags (if you've tagged scenarios with @smoke, @wip, etc.)
+behave --tags=smoke
+```
+
+**Note**: When using `behave` directly (not `behave_run.py`), logic logs still generate in `logs/scenario_logic_logs/`, but the wrapper provides additional error checking.
+
 ### Alternative: Basic Server Tests
 
 ```bash
@@ -205,6 +225,29 @@ def step_impl(context):
     assert final_state.calculated_field == expected_value
 ```
 
+**Understanding the `context` Object:**
+
+The `context` object in Behave is shared across all steps in a scenario, making it perfect for passing data between Given/When/Then steps:
+
+```python
+# Store values in GIVEN steps
+context.customer_id = 123
+context.initial_balance = 1000
+
+# Access in WHEN steps  
+order_data = {"customer_id": context.customer_id, "amount": 500}
+
+# Verify in THEN steps
+assert context.response.status_code == 200
+```
+
+**Common context patterns:**
+- `context.customer_id`, `context.order_id`, etc. - Store entity IDs
+- `context.initial_balance`, `context.before_amount` - Capture "before" state
+- `context.response` - Store API response for later assertions
+- `context.auth_header` - Store authentication token
+- `context.expected_error` - Store expected error for negative tests
+
 ## 🤖 For GitHub Copilot
 
 When generating tests for API Logic Server projects:
@@ -354,10 +397,35 @@ delete_url = f"{base_url}/{EntityName}/{entity_id}/"
 
 ## 📊 Test Reports and Logging
 
-- **Logic Reports**: Generated in `reports/` showing which rules executed
-- **Behave Output**: Standard BDD test results with pass/fail status
-- **Logic Logs**: Detailed rule execution in `logs/scenario_logic_logs/`
-- **Server Logs**: API request/response details and errors
+### Viewing Test Output
+
+After running tests, you can view results in multiple locations:
+
+- **Console Output**: Real-time pass/fail status during test execution
+- **Behave Log**: `logs/behave.log` - Detailed test execution output
+- **Scenario Logic Logs**: `logs/scenario_logic_logs/*.log` - One file per scenario showing rule execution
+- **Server Logs**: API request/response details and errors in server console
+
+### Generating Logic Reports
+
+To create a comprehensive markdown report showing which rules executed in each scenario:
+
+```bash
+# From test/api_logic_server_behave directory
+python behave_logic_report.py run
+```
+
+This generates `reports/Behave Logic Report.md` containing:
+- **Test Scenarios**: All executed scenarios with descriptions
+- **Logic Documentation**: Step docstrings explaining what each test validates
+- **Rules Fired**: Which business logic rules executed during each scenario
+- **Disclosure Areas**: Expandable sections showing detailed logic traces
+
+The report is useful for:
+- Understanding which rules are tested by which scenarios
+- Documenting test coverage for business stakeholders
+- Debugging rule execution order and dependencies
+- Verifying that expected rules actually fired
 
 ## 🔍 Debugging Tests
 

api_logic_server_cli/prototypes/basic_demo/iteration/api/api_discovery/order_b2b.py

@@ -57,27 +57,31 @@ class ServicesEndPoint(safrs.JABase):
         See: https://apilogicserver.github.io/Docs/Sample-Integration/
         Test with swagger, or, from command line:
 
+        CRITICAL: Custom API calls require BOTH "method" and "args" in meta object:
+
         $(venv) ApiLogicServer login --user=admin --password=p
         $(venv) ApiLogicServer curl "'POST' 'http://localhost:5656/api/ServicesEndPoint/OrderB2B'" --data '
-        {"meta": {"args": {"order": {
-            "Account": "Customer 1",
-            "Notes": "Please Rush",
-            "Items": [
-                {
-                "Name": "Product A",
-                "QuantityOrdered": 1
-                },
-                {
-                "Name": "Product B",
-                "QuantityOrdered": 2
-                },
-                {
-                "Name": "Product B",
-                "QuantityOrdered": 2
-                }
+        {"meta": {
+            "method": "OrderB2B",
+            "args": {"order": {
+                "Account": "Customer 1",
+                "Notes": "Please Rush",
+                "Items": [
+                    {
+                    "Name": "Product A",
+                    "QuantityOrdered": 1
+                    },
+                    {
+                    "Name": "Product B",
+                    "QuantityOrdered": 2
+                    },
+                    {
+                    "Name": "Product B",
+                    "QuantityOrdered": 2
+                    }
                 ]
-            }
-        }}}'
+            }}
+        }}'
 
         """
 

api_logic_server_cli/prototypes/basic_demo/ui/my-react-app-cards/README.md

@@ -2,7 +2,9 @@
 
 GenAI-Logic created this app (`genai-logic genai-add-app`) [(docs here)](https://apilogicserver.github.io/Docs/Admin-Vibe/), typically from `ui/admin/admin.yaml`.
 
-We then use CoPilot to add cards, as described in `readme_vibe.md`:
+Use it as a reference example.
+
+We then used CoPilot to add cards, as described in `readme_vibe.md`:
 
 ![cards](product-cards.png)