Merge pull request #23 from KyleKincer/feature/skip-triggers

feat: skip triggers in host project by default

Author: KyleKincer

CLAUDE.md

@@ -6,14 +6,15 @@ A comprehensive unit testing framework for the 4D 4GL platform with test tagging
 
 This project provides a complete testing framework for 4D applications featuring:
 
-- **Auto test discovery** - Finds test classes ending with "Test"  
+- **Auto test discovery** - Finds test classes ending with "Test"
 - **Comment-based tagging** - Organize tests with `// #tags: unit, integration, slow`
 - **Flexible filtering** - Run specific test subsets by name, pattern, or tags
 - **Multiple output formats** - Human-readable and JSON output with terse/verbose modes
 - **CI/CD ready** - Structured JSON output for automated testing pipelines
 - **Parallel test execution** - Run test suites concurrently for improved performance
 - **Automatic transaction management** - Test isolation with automatic rollback
 - **Manual transaction control** - Full transaction lifecycle management for advanced scenarios
+- **Trigger control** - Automatically skip database triggers during tests for true isolation
 
 ## Running Tests
 
@@ -95,13 +96,18 @@ If you need more control or the Makefile doesn't meet your needs:
 --user-param "parallel=true"
 --user-param "parallel=true maxWorkers=4"
 --user-param "parallel=true format=json tags=unit"
+
+# Trigger control
+--user-param "triggers=enabled"   # Enable triggers for all tests
+--user-param "triggers=disabled"  # Disable triggers (default)
+--user-param "triggers=enabled tags=integration"  # Enable triggers for integration tests
 ```
 
 ### Current Test Status
 
-- **Total Tests**: 121 tests across 14 test suites
-- **Pass Rate**: 100% 
-- **Key Test Classes**: TaggingSystemTest, TaggingExampleTest, TestRunnerTest, TestSuiteTest
+- **Total Tests**: 165 tests across 16 test suites
+- **Pass Rate**: 100% (164 passed, 1 skipped)
+- **Key Test Classes**: TaggingSystemTest, TriggerControlTest, TestRunnerTest, TransactionExampleTest
 
 ## Project Structure
 
@@ -309,4 +315,164 @@ Function test_transactionWrapper($t : cs:C1710.Testing)
 | Comment                  | Effect                                   |
 | ------------------------ | ---------------------------------------- |
 | `// #transaction: false` | Disables automatic transactions          |
-| No comment               | Enables automatic transactions (default) |
+| No comment               | Enables automatic transactions (default) |
+
+## Trigger Control During Tests
+
+The framework automatically disables database triggers during test execution to ensure true unit test isolation. This prevents external dependencies and side effects from interfering with tests.
+
+### How It Works
+
+When tests run (either via `tool4d` or from a host project), the framework sets a flag in 4D's shared `Storage`:
+
+```4d
+Storage.triggersDisabled.testMode = True
+```
+
+This flag remains set for the duration of the test run, allowing triggers in the host project to check and skip execution during testing.
+
+### Running Tests from a Host Project
+
+When running tests from a host project (not standalone), you **must** pass the host project's Storage object to enable trigger control:
+
+```4d
+// In your host project's method to run tests
+var $hostStorage : Object
+var $userParams : Object
+
+$hostStorage:=Storage  // Pass the host project's Storage
+$userParams:=New object  // Optional parameters (e.g., "triggers"; "enabled")
+
+// Call the testing component method with cs, Storage, and optional user params
+Testing_RunTestsWithCs(cs; $hostStorage; $userParams)
+```
+
+**Important:** Components have separate Storage objects from their host projects. By passing the host's Storage, the test framework can set flags that your host project's triggers can check.
+
+### Implementing Trigger Control in Host Projects
+
+To make triggers skip execution during tests, add this check at the beginning of each trigger:
+
+```4d
+// At the start of your trigger code
+If (Storage.triggersDisabled#Null) && (Storage.triggersDisabled.testMode=True)
+    return  // Skip trigger execution during tests
+End if
+
+// Normal trigger logic continues here...
+```
+
+### Example: Complete Trigger Implementation
+
+```4d
+// Table trigger with test mode support
+If (Storage.triggersDisabled#Null) && (Storage.triggersDisabled.testMode=True)
+    return
+End if
+
+// Normal trigger logic
+Case of
+    : (Trigger event=On Saving New Record Event)
+        // Validate and set default values
+        If ([MyTable]requiredField="")
+            [MyTable]requiredField:="DefaultValue"
+        End if
+
+    : (Trigger event=On Saving Existing Record Event)
+        // Update modification timestamp
+        [MyTable]modifiedAt:=Current date
+End case
+```
+
+### Benefits of Trigger Control
+
+- **True Unit Testing**: Tests can focus on business logic without trigger side effects
+- **Faster Tests**: Skipping triggers reduces test execution time
+- **Test Isolation**: Each test runs in a clean state without trigger interference
+- **Flexibility**: Easily enable triggers for integration tests when needed
+
+### Configuring Trigger Behavior
+
+The framework provides flexible control over when triggers execute:
+
+#### Global Trigger Control via User Parameters
+
+Control the default trigger behavior for all tests using the `triggers` parameter:
+
+```bash
+# Enable triggers for all tests (default is disabled)
+make test triggers=enabled
+
+# Explicitly disable triggers (default behavior)
+make test triggers=disabled
+
+# With other parameters
+make test format=json triggers=enabled tags=integration
+```
+
+**Default Behavior**: Triggers are **disabled by default** (`triggers=disabled`) to ensure true unit test isolation.
+
+#### Per-Test Trigger Control via Comments
+
+Individual tests can override the global setting using comment annotations:
+
+```4d
+// #triggers: enabled
+Function test_withTriggersEnabled($t : cs.Testing)
+    // This test will have triggers enabled regardless of global setting
+    // Useful for integration tests that need to verify trigger behavior
+
+// #triggers: disabled
+Function test_withTriggersDisabled($t : cs.Testing)
+    // This test will have triggers disabled regardless of global setting
+    // Useful for unit tests that need isolation
+
+Function test_defaultBehavior($t : cs.Testing)
+    // No annotation - uses global setting from triggers parameter
+```
+
+#### Use Cases
+
+**Unit Tests (triggers disabled):**
+```4d
+// #triggers: disabled
+Function test_calculateTotal($t : cs.Testing)
+    // Test business logic without trigger side effects
+    // Default behavior - no annotation needed
+```
+
+**Integration Tests (triggers enabled):**
+```4d
+// #tags: integration
+// #triggers: enabled
+Function test_orderProcessingWithTriggers($t : cs.Testing)
+    // Test complete flow including trigger execution
+```
+
+**Hybrid Approach:**
+```bash
+# Run unit tests with triggers disabled (default)
+make test-unit
+
+# Run integration tests with triggers enabled
+make test-integration triggers=enabled
+```
+
+### When to Allow Triggers
+
+For integration tests that specifically need to test trigger behavior:
+
+1. **Use per-test annotations** with `// #triggers: enabled`
+2. **Enable globally** with `triggers=enabled` parameter for integration test suites
+3. **Tag appropriately** using `// #tags: integration` for filtering
+4. **Test trigger logic directly** by extracting it into testable functions
+5. **Mock trigger behavior** in unit tests using test doubles
+
+### Implementation Notes
+
+- The `Storage.triggersDisabled.testMode` flag is automatically managed by the test framework
+- Per-test trigger control automatically restores the default behavior after each test
+- No manual cleanup is required - flags persist only for the test process lifetime
+- Works in both interpreted and compiled modes
+- Compatible with parallel test execution - each worker process has its own Storage state
+- Test-level annotations take precedence over global `triggers` parameter

testing/Project/Sources/Classes/ParallelTestRunner.4dm

@@ -9,8 +9,8 @@ property sharedResults : Object        // Shared storage for collecting results
 property completedSuites : Integer     // Counter for completed suites
 property sequentialSuites : Collection // Suites that opted out of parallel execution
 
-Class constructor($cs : 4D:C1709.Object)
-	Super:C1705($cs)
+Class constructor($cs : 4D:C1709.Object; $hostStorage : 4D:C1709.Object; $userParams : 4D:C1709.Object)
+	Super:C1705($cs; $hostStorage; $userParams)
 	This:C1470.parallelMode:=False:C215
         This:C1470.maxWorkers:=This:C1470._getDefaultWorkerCount()
         This:C1470.workerProcesses:=[]

testing/Project/Sources/Classes/TestRunner.4dm

@@ -1,4 +1,5 @@
 property classStore : 4D:C1709.Object  // Class store from the calling project
+property hostStorage : 4D:C1709.Object  // Host project's Storage for trigger control
 property testSuites : Collection  // Collection of cs._TestSuite
 property results : Object  // Test results summary
 property outputFormat : Text  // "human", "json", "junit"
@@ -7,23 +8,93 @@ property testPatterns : Collection  // Collection of test patterns to match
 property includeTags : Collection  // Tags to include (OR logic)
 property excludeTags : Collection  // Tags to exclude
 property requireAllTags : Collection  // Tags that must all be present (AND logic)
+property userParams : Object  // User parameters passed to the runner
+property disableTriggersByDefault : Boolean  // Whether triggers are disabled by default
 
-Class constructor($cs : 4D:C1709.Object)
+Class constructor($cs : 4D:C1709.Object; $hostStorage : 4D:C1709.Object; $userParams : Object)
 	This:C1470.classStore:=$cs || cs:C1710
+	This:C1470.hostStorage:=$hostStorage  // Can be Null for component-only testing
+	This:C1470.userParams:=$userParams || This:C1470._parseUserParams()  // Use provided params or parse from command line
 	This:C1470.testSuites:=[]
 	This:C1470._initializeResults()
 	This:C1470._determineOutputFormat()
 	This:C1470._parseTestPatterns()
 	This:C1470._parseTagFilters()
+	This:C1470._determineTriggerDefaultBehavior()
 
 Function run()
+        This:C1470._initializeTriggerControl()
         This:C1470._prepareErrorHandlingStorage()
         var $handlerState : Object
         $handlerState:=This:C1470._installErrorHandler()
         This:C1470._runInternal()
         This:C1470._captureGlobalErrors()
         This:C1470._restoreErrorHandler($handlerState)
 
+Function _determineTriggerDefaultBehavior()
+        // Determine the default trigger behavior based on user parameters
+        // Default is to disable triggers (testMode=true) unless explicitly enabled
+        var $triggerParam : Text
+        $triggerParam:=This:C1470.userParams.triggers || ""
+
+        // triggers=enabled means triggers are ON by default (testMode=false)
+        // triggers=disabled (or omitted) means triggers are OFF by default (testMode=true)
+        This:C1470.disableTriggersByDefault:=($triggerParam#"enabled")
+
+Function _initializeTriggerControl()
+        // Initialize trigger control flag in the appropriate Storage
+        var $storageToUse : 4D:C1709.Object
+        $storageToUse:=(This:C1470.hostStorage#Null:C1517) ? This:C1470.hostStorage : Storage:C1525
+
+        Use ($storageToUse)
+                If ($storageToUse.triggersDisabled=Null:C1517)
+                        $storageToUse.triggersDisabled:=New shared object:C1526("testMode"; This:C1470.disableTriggersByDefault)
+                Else
+                        Use ($storageToUse.triggersDisabled)
+                                $storageToUse.triggersDisabled.testMode:=This:C1470.disableTriggersByDefault
+                        End use
+                End if
+        End use
+
+Function enableTriggersForTest()
+        // Enable triggers for the current test (sets testMode=false)
+        var $storageToUse : 4D:C1709.Object
+        $storageToUse:=(This:C1470.hostStorage#Null:C1517) ? This:C1470.hostStorage : Storage:C1525
+
+        Use ($storageToUse)
+                If ($storageToUse.triggersDisabled#Null:C1517)
+                        Use ($storageToUse.triggersDisabled)
+                                $storageToUse.triggersDisabled.testMode:=False:C215
+                        End use
+                End if
+        End use
+
+Function disableTriggersForTest()
+        // Disable triggers for the current test (sets testMode=true)
+        var $storageToUse : 4D:C1709.Object
+        $storageToUse:=(This:C1470.hostStorage#Null:C1517) ? This:C1470.hostStorage : Storage:C1525
+
+        Use ($storageToUse)
+                If ($storageToUse.triggersDisabled#Null:C1517)
+                        Use ($storageToUse.triggersDisabled)
+                                $storageToUse.triggersDisabled.testMode:=True:C214
+                        End use
+                End if
+        End use
+
+Function restoreDefaultTriggerBehavior()
+        // Restore the default trigger behavior after a test
+        var $storageToUse : 4D:C1709.Object
+        $storageToUse:=(This:C1470.hostStorage#Null:C1517) ? This:C1470.hostStorage : Storage:C1525
+
+        Use ($storageToUse)
+                If ($storageToUse.triggersDisabled#Null:C1517)
+                        Use ($storageToUse.triggersDisabled)
+                                $storageToUse.triggersDisabled.testMode:=This:C1470.disableTriggersByDefault
+                        End use
+                End if
+        End use
+
 Function _prepareErrorHandlingStorage()
         Use (Storage:C1525)
                 If (Storage:C1525.testErrors=Null:C1517)