ApiLogicServer 15.0.61__py3-none-any.whl → 15.1.0__py3-none-any.whl

api_logic_server_cli/prototypes/manager/samples/basic_demo/test/basic/server_test.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+import requests
+import logging
+import subprocess
+import socket
+
+
+def prt(msg: any) -> None:
+    print(msg)
+
+
+def get_project_dir() -> str:
+    """
+    :return: ApiLogicServer dir, eg, /Users/val/dev/ApiLogicServer
+    """
+    path = Path(__file__)
+    parent_path = path.parent
+    parent_path = parent_path.parent
+    return parent_path
+
+
+def server_tests(host, port, version):
+    """ called by api_logic_server_run.py, for any tests on server start
+        args
+            host - server host
+            port - server port
+            version - ApiLogicServer version
+    """
+    ...  # Your Code Goes Here
+
+if __name__ == "__main__":
+   # only to run when not called via 'import' here
+   server_tests("localhost", "5656", "v0")

api_logic_server_cli/prototypes/manager/samples/basic_demo/test/readme_test.md

@@ -0,0 +1,395 @@
+# API Logic Server Testing Guide
+
+## Overview
+
+This directory contains comprehensive tests for API Logic Server projects, designed to validate business logic rules, API endpoints, security, and data integrity. The testing framework emphasizes **business logic validation** through declarative rules rather than just basic CRUD operations.
+
+## 🎯 What Gets Tested
+
+- **Business Logic Rules**: Declarative rules for sums, formulas, constraints, and events
+- **API Endpoints**: REST API functionality and JSON:API compliance
+- **Security**: Authentication, authorization, and role-based access control
+- **Data Integrity**: Database constraints, cascading updates, and transactions
+- **Integration**: Logic engine, database, and API layer integration
+
+## 📁 Test Structure
+
+```
+test/
+├── readme_test.md                 # This guide
+├── api_logic_server_behave/       # Primary BDD testing framework
+│   ├── behave_run.py             # Main test runner
+│   ├── behave_logic_report.py    # Report generator
+│   ├── features/                 # Gherkin feature files
+│   │   ├── *.feature            # Business logic test scenarios
+│   │   └── steps/               # Python step implementations
+│   ├── logs/                    # Test execution logs
+│   └── reports/                 # Generated test reports
+└── basic/                       # Simple server tests
+    ├── server_test.py           # Basic API functionality tests
+    └── results/                 # Basic test results
+```
+
+## 🚀 Running Tests
+
+### 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 your database from backup
+
+### Primary Testing Method: Behave (BDD)
+
+```bash
+# From project root
+cd test/api_logic_server_behave
+python behave_run.py
+
+# Or in VS Code
+# Use "Behave Run" configuration (F5)
+# In Debug Console, select "Behave Run" from dropdown (not server log)
+```
+
+### Alternative: Basic Server Tests
+
+```bash
+# From project root
+cd test/basic
+python server_test.py go
+```
+
+**Note**: Basic tests require `SECURITY_ENABLED = False` in `config/config.py`
+
+## 📝 Common Test Scenarios
+
+API Logic Server projects typically test these business patterns:
+
+### 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
+
+*Example: In Northwind, order ready/not-ready states affect customer balances through automatic sum rules.*
+
+### Entity Management
+- **Audit Trails**: Automatic logging of critical changes
+- **Derived Attributes**: Calculated fields and transformations
+- **Business Rules**: Validation and constraint enforcement
+
+*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 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
+
+### Identifying Test Data
+When creating tests, identify stable test entities in your database:
+
+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
+
+### 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. **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
+
+### Generic Feature Structure
+
+```gherkin
+Feature: [Business Process Name]
+
+  Scenario: [Specific Business Rule Test]
+     Given [Initial business state]
+      When [Business action is performed]
+      Then [Expected business outcome occurs]
+      And [Additional validations]
+```
+
+### Generic Step Implementation Pattern
+
+```python
+# features/steps/[feature_name].py
+from behave import *
+import test_utils
+import requests
+import json
+from dotmap import DotMap
+
+@given('[Initial business state]')
+def step_impl(context):
+    # Get initial state of your key business entities
+    # Store in context for later comparison
+    context.initial_state = get_entity_state(entity_id)
+
+@when('[Business action is performed]')
+def step_impl(context):
+    # 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 business outcome occurs]')
+def step_impl(context):
+    # 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
+```
+
+## 🤖 For GitHub Copilot
+
+When generating tests for API Logic Server projects:
+
+### Key Patterns to Follow
+
+1. **Focus on Business Logic**: Test declarative rules, not just CRUD operations
+2. **Use Behave Framework**: Create `.feature` files with Gherkin syntax
+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 (handles both SQL and Keycloak)
+header = test_utils.login(user='username')  # Returns auth header dict
+
+# Logging (appears in console and scenario log files)
+test_utils.prt("Test message", "scenario_name")
+
+# 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)
+```
+
+### Business Logic Testing Patterns
+
+#### Testing Sum Rules
+```python
+# Pattern: Test that derived sums update automatically
+# Example: Customer.Balance = sum(Order.AmountTotal where not shipped)
+
+@given('Entity with calculated sum field')
+def step_impl(context):
+    context.parent_before = get_parent_entity(parent_id)
+
+@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)
+
+@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
+# 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()
+```
+
+#### 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
+```
+
+### 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
+
+- **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
+
+## 🔍 Debugging Tests
+
+### 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 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

api_logic_server_cli/prototypes/manager/samples/basic_demo/ui/admin/admin.yaml

@@ -0,0 +1,173 @@
+about:
+  date: August 09, 2025 08:12:46
+  recent_changes: works with modified safrs-react-admin
+  version: 0.0.0
+api_root: '{http_type}://{swagger_host}:{port}/{api}'
+authentication: '{system-default}'
+info:
+  number_relationships: 4
+  number_tables: 5
+info_toggle_checked: true
+resources:
+  Customer:
+    attributes:
+    - label: ' name*'
+      name: name
+      search: true
+      sort: true
+    - name: balance
+      type: DECIMAL
+    - name: credit_limit
+      type: DECIMAL
+    - name: email
+    - name: email_opt_out
+      type: Boolean
+    - name: id
+    tab_groups:
+    - direction: tomany
+      fks:
+      - customer_id
+      name: OrderList
+      resource: Order
+    - direction: tomany
+      fks:
+      - customer_id
+      name: SysEmailList
+      resource: SysEmail
+    type: Customer
+    user_key: name
+  Item:
+    attributes:
+    - label: ' id*'
+      name: id
+      search: true
+      sort: true
+    - name: order_id
+    - name: product_id
+      required: true
+    - name: quantity
+      required: true
+    - name: amount
+      type: DECIMAL
+    - name: unit_price
+      type: DECIMAL
+    tab_groups:
+    - direction: toone
+      fks:
+      - order_id
+      name: order
+      resource: Order
+    - direction: toone
+      fks:
+      - product_id
+      name: product
+      resource: Product
+    type: Item
+    user_key: id
+  Order:
+    attributes:
+    - label: ' id*'
+      name: id
+      search: true
+      sort: true
+    - name: customer_id
+      required: true
+    - name: notes
+    - name: CreatedOn
+      type: DATE
+    - name: amount_total
+      type: DECIMAL
+    - name: date_shipped
+      type: DATE
+    tab_groups:
+    - direction: tomany
+      fks:
+      - order_id
+      name: ItemList
+      resource: Item
+    - direction: toone
+      fks:
+      - customer_id
+      name: customer
+      resource: Customer
+    type: Order
+    user_key: id
+  Product:
+    attributes:
+    - label: ' name*'
+      name: name
+      search: true
+      sort: true
+    - name: unit_price
+      type: DECIMAL
+    - name: id
+    tab_groups:
+    - direction: tomany
+      fks:
+      - product_id
+      name: ItemList
+      resource: Item
+    type: Product
+    user_key: name
+  SysEmail:
+    attributes:
+    - label: ' id*'
+      name: id
+      search: true
+      sort: true
+    - name: customer_id
+      required: true
+    - name: subject
+    - name: message
+    - name: CreatedOn
+      type: DATETIME
+    tab_groups:
+    - direction: toone
+      fks:
+      - customer_id
+      name: customer
+      resource: Customer
+    type: SysEmail
+    user_key: id
+  mcp-SysMcp:
+    attributes:
+    - name: request
+      type: textarea
+    - label: ' id*'
+      name: id
+      search: true
+      sort: true
+      show_when: isInserting == false
+    type: SysMcp
+    user_key: id
+settings:
+  HomeJS: /admin-app/home.js
+  max_list_columns: 8
+  style_guide:
+    applicationLocales:
+    - en
+    - es
+    currency_symbol: $
+    currency_symbol_position: left
+    date_format: LL
+    decimal_max: '1000000000'
+    decimal_min: '2'
+    decimal_separator: .
+    detail_mode: tab
+    edit_on_mode: dblclick
+    exclude_listpicker: false
+    include_translation: 'false'
+    keycloak_client_id: alsclient
+    keycloak_realm: kcals
+    keycloak_url: http://localhost:8080
+    locale: en
+    max_decimal_digits: '4'
+    min_decimal_digits: '2'
+    new_mode: dialog
+    pick_style: list
+    row_height: small,
+    serviceType: JSONAPI
+    startSessionPath: /auth/login
+    style: light
+    thousand_separator: ','
+    use_keycloak: 'false'