ApiLogicServer 15.1.3__py3-none-any.whl → 15.2.3__py3-none-any.whl

api_logic_server_cli/prototypes/nw/test/readme_test_nw.md

@@ -1,3 +1,5 @@
+The tests here were manually created.  Contrast the the basic_demo sample, which contains tests created by the AI Assistant.
+
 # API Logic Server Testing Guide
 
 ## Overview
@@ -21,9 +23,7 @@ test/
 │   ├── behave_run.py             # Main test runner
 │   ├── behave_logic_report.py    # Report generator
 │   ├── features/                 # Gherkin feature files
-│   │   ├── place_order.feature   # Core business logic scenarios
-│   │   ├── salary_change.feature # Employee management tests
-│   │   ├── authorization.feature # Security tests
+│   │   ├── *.feature            # Business logic test scenarios
 │   │   └── steps/               # Python step implementations
 │   ├── logs/                    # Test execution logs
 │   └── reports/                 # Generated test reports
@@ -37,7 +37,7 @@ test/
 ### Prerequisites
 1. **Start API Logic Server**: `python api_logic_server_run.py` or press F5
 2. **Install behave**: `pip install behave` (if not already installed)
-3. **Database State**: Tests restore data automatically, but if tests fail mid-execution, restore `database/db.sqlite` from backup
+3. **Database State**: Tests restore data automatically, but if tests fail mid-execution, restore your database from backup
 
 ### Primary Testing Method: Behave (BDD)
 
@@ -51,6 +51,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
@@ -61,89 +81,175 @@ python server_test.py go
 
 **Note**: Basic tests require `SECURITY_ENABLED = False` in `config/config.py`
 
-## 📝 Test Scenarios
-
-### Core Business Logic (`place_order.feature`)
+## 📝 Common Test Scenarios
 
-Tests the fundamental business rules of the sample Northwind application:
+API Logic Server projects typically test these business patterns:
 
-- **Order State Management**: Ready/Not Ready flag changes
-- **Credit Checking**: Validates customer credit limits
-- **Balance Calculations**: Automatic customer balance adjustments
-- **Inventory Management**: Product reordering and stock updates
-- **Notifications**: Email alerts to sales representatives
-- **Integration**: Kafka message publishing
-- **Constraint Validation**: Prevents shipping empty orders
+### Core Business Logic
+- **State Management**: Entity status changes and their cascading effects
+- **Credit/Limit Checking**: Validation against business constraints
+- **Balance/Total Calculations**: Automatic sum and formula derivations
+- **Inventory/Resource Management**: Allocation and availability tracking
+- **Notifications**: Email alerts and external system integration
+- **Constraint Validation**: Business rule enforcement
 
-### Employee Management (`salary_change.feature`)
+*Example: In Northwind, order ready/not-ready states affect customer balances through automatic sum rules.*
 
-- **Audit Trail**: Automatic logging of salary changes
-- **Derived Attributes**: ProperSalary calculations
-- **Business Rules**: Minimum raise requirements
+### Entity Management
+- **Audit Trails**: Automatic logging of critical changes
+- **Derived Attributes**: Calculated fields and transformations
+- **Business Rules**: Validation and constraint enforcement
 
-### Security (`authorization.feature`)
+*Example: Employee salary changes create audit records and validate minimum raise amounts.*
 
+### Security Testing
 - **Authentication**: Login/logout functionality
 - **Role-Based Access**: Permission validation
-- **Data Filtering**: Row-level security
+- **Data Filtering**: Row-level security based on user roles
+
+## 🧪 Test Data Strategy
+
+### Testing Business Logic Derivations
+
+**Best Practice for Derivation Testing:**
+
+When testing business logic derivations (sums, formulas, constraints), follow this pattern:
+
+1. **Read Initial State**: Capture the starting values before the transaction
+2. **Execute Transaction**: Perform the business operation (create order, update quantity, etc.)
+3. **Read Final State**: Capture the resulting values after business logic execution
+4. **Compare Changes**: Verify the differences match expected derivation behavior
+
+```python
+@when('Customer places order for ${amount:d}')
+def step_impl(context, amount):
+    # 1. Read initial state
+    customer_response = requests.get(f"{BASE_URL}/api/Customer/1")
+    context.initial_balance = customer_response.json()['data']['attributes']['balance']
+    
+    # 2. Execute transaction
+    order_data = {"customer_id": 1, "amount_total": amount}
+    context.response = requests.post(f"{BASE_URL}/api/Order", json=order_data)
+    
+@then('Customer balance increases by ${expected_increase:d}')
+def step_impl(context, expected_increase):
+    # 3. Read final state
+    customer_response = requests.get(f"{BASE_URL}/api/Customer/1")
+    final_balance = customer_response.json()['data']['attributes']['balance']
+    
+    # 4. Compare changes
+    actual_increase = final_balance - context.initial_balance
+    assert actual_increase == expected_increase, f"Balance changed by {actual_increase}, expected {expected_increase}"
+```
+
+**Why This Approach Works:**
+- ✅ **Independent of Initial Data**: Tests work regardless of starting database state
+- ✅ **Focuses on Business Logic**: Verifies the rule behavior, not absolute values
+- ✅ **Robust Against Multiple Runs**: Tests remain valid after repeated execution
+- ✅ **Clear Intent**: Shows exactly what the business rule should accomplish
 
-## 🧪 Test Data
+### Identifying Test Data
+When creating tests, identify stable test entities in your database:
 
-Tests use consistent, known data for predictable results:
+1. **Key Business Entities**: Main domain objects (customers, orders, products, etc.)
+2. **Known State**: Entities with predictable initial values
+3. **Relationships**: Connected entities that demonstrate rule cascading
+4. **Edge Cases**: Boundary conditions for constraints and validations
 
-| Entity | ID/Key | Key Attributes | Purpose |
-|--------|--------|----------------|---------|
-| Customer | ALFKI | Balance: 2102, CreditLimit varies | Credit checking, balance calculations |
-| Order | 10643 | Amount: 1086 | Order processing, shipping logic |
-| Employee | 5 (Buchanan) | Salary: 95k | Salary management, audit testing |
+### Test Data Documentation
+Document your test data in comments or separate files:
+
+```python
+"""
+Test Data Used:
+- Primary Customer: [CustomerID] with [known balance/status]
+- Test Order: [OrderID] with [known amount]
+- Test Employee: [EmployeeID] with [known salary]
+- Constraint Limits: [specific values that trigger validations]
+"""
+```
 
 ## 🔧 For Developers
 
 ### Adding New Tests
 
-1. **Create Feature File**: Add `.feature` file in `features/` using Gherkin syntax
-2. **Implement Steps**: Create corresponding `.py` file in `features/steps/`
-3. **Use Test Utilities**: Import `test_utils.py` for common functions
-4. **Follow Patterns**: Reference existing tests for authentication, logging, and assertions
+1. **Identify Business Scenario**: What business rule or process needs testing?
+2. **Create Feature File**: Add `.feature` file in `features/` using Gherkin syntax
+3. **Implement Steps**: Create corresponding `.py` file in `features/steps/`
+4. **Use Test Utilities**: Import `test_utils.py` for common functions
+5. **Follow Patterns**: Reference existing tests for authentication, logging, and assertions
 
-### Example Feature Structure
+### Generic Feature Structure
 
 ```gherkin
-Feature: My New Feature
+Feature: [Business Process Name]
 
-  Scenario: Test Scenario Name
-     Given Initial condition
-      When Action is performed
-      Then Expected result occurs
+  Scenario: [Specific Business Rule Test]
+     Given [Initial business state]
+      When [Business action is performed]
+      Then [Expected business outcome occurs]
+      And [Additional validations]
 ```
 
-### Example Step Implementation
+### Generic Step Implementation Pattern
 
 ```python
-# features/steps/my_feature.py
+# features/steps/[feature_name].py
 from behave import *
 import test_utils
 import requests
 import json
+from dotmap import DotMap
 
-@given('Initial condition')
+@given('[Initial business state]')
 def step_impl(context):
-    # Setup code
-    pass
+    # Get initial state of your key business entities
+    # Store in context for later comparison
+    context.initial_state = get_entity_state(entity_id)
 
-@when('Action is performed')
+@when('[Business action is performed]')
 def step_impl(context):
-    # Action code
-    header = test_utils.login()  # Get auth header
-    # Make API calls
-    pass
+    # Perform the business operation via API
+    header = test_utils.login()  # Get auth header if needed
+    
+    # Make API call (POST, PATCH, DELETE, etc.)
+    api_url = f'http://localhost:5656/api/[YourEntity]/[id]/'
+    response = requests.patch(url=api_url, json=your_data, headers=header)
+    
+    # Store response for validation
+    context.response = response
 
-@then('Expected result occurs')
+@then('[Expected business outcome occurs]')
 def step_impl(context):
-    # Assertion code
-    pass
+    # Verify the business rule executed correctly
+    # Check entity state changes, calculated fields, etc.
+    final_state = get_entity_state(entity_id)
+    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:
@@ -152,73 +258,208 @@ When generating tests for API Logic Server projects:
 
 1. **Focus on Business Logic**: Test declarative rules, not just CRUD operations
 2. **Use Behave Framework**: Create `.feature` files with Gherkin syntax
-3. **Test Authentication**: Include login/security in API calls
-4. **Verify Rule Execution**: Check that LogicBank rules fire correctly
-5. **Test Constraints**: Verify business rule violations are caught
-6. **Check Cascading Updates**: Ensure changes propagate correctly
+3. **Test Rule Execution**: Verify LogicBank rules fire and produce correct results
+4. **Test Constraints**: Verify business rule violations are properly caught
+5. **Check Cascading Updates**: Ensure changes propagate through rule chains
+6. **Include Authentication**: Use proper auth headers for API calls
 
 ### Common Test Utilities
 
 ```python
 import test_utils
 
-# Authentication
-header = test_utils.login(user='aneu')  # Returns auth header
+# Authentication (handles both SQL and Keycloak)
+header = test_utils.login(user='username')  # Returns auth header dict
 
-# Logging (appears in both console and log files)
+# Logging (appears in console and scenario log files)
 test_utils.prt("Test message", "scenario_name")
 
-# API calls with auth
+# Typical API call patterns
 r = requests.get(url=api_url, headers=header)
+r = requests.post(url=api_url, json=data, headers=header)
 r = requests.patch(url=api_url, json=data, headers=header)
+r = requests.delete(url=api_url, headers=header)
 ```
 
-### Security Considerations
+### Business Logic Testing Patterns
 
-- Tests can run with or without security enabled
-- Use `test_utils.login()` for authenticated requests
-- Handle both SQL and Keycloak authentication providers
-- Check `Config.SECURITY_ENABLED` flag
+#### Testing Sum Rules
+```python
+# Pattern: Test that derived sums update automatically
+# Example: Customer.Balance = sum(Order.AmountTotal where not shipped)
 
-### Business Logic Testing Patterns
+@given('Entity with calculated sum field')
+def step_impl(context):
+    context.parent_before = get_parent_entity(parent_id)
 
-1. **Setup**: Get initial state (e.g., customer balance)
-2. **Action**: Perform business operation (e.g., place order)
-3. **Verify**: Check rule execution results (e.g., balance updated, constraints enforced)
-4. **Cleanup**: Data is automatically restored
+@when('Child entity is modified')
+def step_impl(context):
+    # Create/update child entity
+    header = test_utils.login()
+    child_data = {"amount": 100, "parent_id": parent_id}
+    r = requests.post(url=child_api_url, json=child_data, headers=header)
 
-### Sample Rule Testing
+@then('Parent sum field updates automatically')
+def step_impl(context):
+    parent_after = get_parent_entity(parent_id)
+    expected_sum = context.parent_before.sum_field + 100
+    assert parent_after.sum_field == expected_sum
+```
 
+#### Testing Constraint Rules
 ```python
-# Test a sum rule: Customer.Balance = sum(Order.AmountTotal where not shipped)
-def test_balance_calculation():
-    # 1. Get initial customer state
-    customer_before = get_customer('ALFKI')
-    
-    # 2. Create/modify order
-    create_order_for_customer('ALFKI', amount=100)
-    
-    # 3. Verify balance updated automatically
-    customer_after = get_customer('ALFKI')
-    assert customer_after.Balance == customer_before.Balance + 100
+# Pattern: Test that business constraints are enforced
+# Example: Customer.Balance <= Customer.CreditLimit
+
+@when('Action violates business constraint')
+def step_impl(context):
+    header = test_utils.login()
+    # Data that should violate constraint
+    violating_data = {"amount": 99999}  # Exceeds credit limit
+    r = requests.patch(url=api_url, json=violating_data, headers=header)
+    context.response = r
+
+@then('Constraint violation is detected')
+def step_impl(context):
+    assert context.response.status_code >= 400  # Should fail
+    error_message = context.response.json()
+    assert "constraint" in error_message.get("message", "").lower()
 ```
 
-## 📊 Test Reports
+#### Testing Formula Rules
+```python
+# Pattern: Test that formulas calculate correctly
+# Example: OrderDetail.Amount = Quantity * UnitPrice
+
+@when('Formula inputs are changed')
+def step_impl(context):
+    header = test_utils.login()
+    update_data = {"quantity": 5, "unit_price": 10.50}
+    r = requests.patch(url=api_url, json=update_data, headers=header)
+
+@then('Formula result updates automatically')
+def step_impl(context):
+    updated_entity = get_entity(entity_id)
+    expected_amount = 5 * 10.50
+    assert updated_entity.amount == expected_amount
+```
 
-- **Logic Reports**: Generated in `reports/` showing which rules executed
-- **Behave Output**: Standard BDD test results
-- **Logic Logs**: Detailed rule execution in `logs/scenario_logic_logs/`
+### Security Testing Patterns
+
+```python
+# Test role-based access
+@given('User with specific role')
+def step_impl(context):
+    context.auth_header = test_utils.login(user='role_specific_user')
+
+@when('User accesses restricted resource')
+def step_impl(context):
+    r = requests.get(url=restricted_api_url, headers=context.auth_header)
+    context.response = r
+
+@then('Access is properly controlled')
+def step_impl(context):
+    # Should succeed for authorized users, fail for others
+    if user_has_permission:
+        assert context.response.status_code == 200
+    else:
+        assert context.response.status_code in [401, 403]
+```
+
+### Project-Specific Considerations
+
+When creating tests for a specific project:
+
+1. **Identify Key Business Rules**: What are the main business logic rules in `logic/declare_logic.py`?
+2. **Map Test Scenarios**: Create scenarios that exercise each major rule type
+3. **Use Domain Language**: Write scenarios in business terms, not technical terms
+4. **Test Rule Interactions**: Verify that rules work together correctly
+5. **Include Edge Cases**: Test boundary conditions and error cases
+
+### API Endpoint Patterns
+
+```python
+# Standard API endpoint patterns for any project
+base_url = "http://localhost:5656/api"
+
+# Get entity with relationships
+get_url = f"{base_url}/{EntityName}/{entity_id}/?include={RelatedEntity}List"
+
+# Create new entity
+post_url = f"{base_url}/{EntityName}/"
+post_data = {"data": {"attributes": {...}, "type": "EntityName"}}
+
+# Update existing entity  
+patch_url = f"{base_url}/{EntityName}/{entity_id}/"
+patch_data = {"data": {"attributes": {...}, "type": "EntityName", "id": entity_id}}
+
+# Delete entity
+delete_url = f"{base_url}/{EntityName}/{entity_id}/"
+```
+
+## 📊 Test Reports and Logging
+
+### 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
 
-- **Check Logs**: Review `logs/scenario_logic_logs/<scenario>.log`
-- **Use Debug Console**: In VS Code, select "Behave Run" from dropdown
-- **Server Logs**: Check server console for API errors
-- **Database State**: Restore `database/db.sqlite` if tests fail mid-execution
+### Common Issues and Solutions
+
+1. **Authentication Failures**: Check `Config.SECURITY_ENABLED` and login credentials
+2. **Database State**: If tests fail, restore database to clean state
+3. **Rule Not Firing**: Verify rule syntax in `logic/declare_logic.py`
+4. **API Errors**: Check server console and `logs/scenario_logic_logs/`
+
+### Debug Steps
+
+```python
+# Add debug logging to your test steps
+test_utils.prt(f"Before: {entity_before}", scenario_name)
+test_utils.prt(f"API Response: {response.text}", scenario_name)
+test_utils.prt(f"After: {entity_after}", scenario_name)
+```
 
 ## ⚠️ Important Notes
 
 - **Data Restoration**: Tests automatically restore data, but partial failures may require manual database restore
-- **Security Mode**: Behave tests work with security enabled; basic tests require security disabled
-- **Rule Engine**: Tests specifically validate LogicBank rule execution, not just API responses
-- **Performance**: Tests include logic optimization verification (rule pruning, etc.)
+- **Security Mode**: Behave tests work with security enabled; basic tests require security disabled  
+- **Rule Engine Focus**: Tests specifically validate LogicBank rule execution, not just API responses
+- **Performance Testing**: Tests can include logic optimization verification (rule pruning, etc.)
+- **Concurrent Testing**: Be aware of database locking if running multiple test suites simultaneously
+
+## 🎯 Best Practices
+
+1. **Test Business Logic First**: Focus on rules and constraints before API mechanics
+2. **Use Meaningful Test Data**: Choose entities and values that clearly demonstrate rule behavior
+3. **Document Test Scenarios**: Explain the business purpose of each test
+4. **Keep Tests Independent**: Each scenario should work regardless of other test execution
+5. **Verify Rule Execution**: Don't just test API responses, verify that business logic actually ran
+6. **Test Error Cases**: Include scenarios that should fail due to business constraints