piper-utils 1.1.25 → 1.1.27

package/Test-Prompt.md

@@ -0,0 +1,303 @@
+# Test Spy Creation System Prompt
+
+## run test
+
+```PowerShell
+npm run test
+```
+#### do not use && in Power Shell
+
+## Overview
+When writing unit tests for functions that interact with external dependencies, follow these strict guidelines for creating spies. Each test should be self-contained with its own spies defined inline, not in beforeEach blocks.
+
+## What TO Spy On (External Boundaries Only)
+
+### 1. Database Operations
+```javascript
+spyOn(Payment, 'findOne').and.returnValue(Promise.resolve(mockData));
+spyOn(Order, 'create').and.returnValue(Promise.resolve(mockData));
+spyOn(Company, 'findOne').and.returnValue(Promise.resolve(mockData));
+spyOn(Model, 'destroy').and.returnValue(Promise.resolve());
+```
+
+### 2. External Service Calls
+```javascript
+// HTTP requests
+spyOn(axios, 'post').and.returnValue({ data: mockResponse });
+spyOn(axios, 'get').and.returnValue({ data: mockResponse });
+spyOn(axios, 'put').and.returnValue({ data: mockResponse });
+
+// Third-party services
+spyOn(flopay, 'processPayment').and.returnValue(Promise.resolve(mockResponse));
+spyOn(S3, 's3').and.returnValue(Promise.resolve());
+```
+
+### 3. Email/SMS Services
+```javascript
+spyOn(inboxUtils, 'sendEmailToInbox').and.returnValue(Promise.resolve());
+spyOn(inboxUtils, 'sendTextToInbox').and.returnValue(Promise.resolve());
+spyOn(htmlTemplateUtils, 'sendGridInvoiceOrReceiptTemplate').and.returnValue(Promise.resolve());
+```
+
+### 4. Audit/Logging Mechanisms
+```javascript
+spyOn(audit, 'attach').and.returnValue(Promise.resolve());
+```
+
+### 5. Database Transactions
+```javascript
+spyOn(db, 'getConnection').and.returnValue({
+    transaction: () => ({
+        commit: () => {},
+        rollback: () => {}
+    })
+});
+```
+
+### 6. Webhook Utilities
+```javascript
+spyOn(webhookUtils, 'sendToWebhook').and.returnValue(Promise.resolve());
+```
+
+### 7. Route-level Functions (when testing other routes)
+```javascript
+spyOn(orderRoutes, 'updateOrderStatus').and.returnValue(Promise.resolve());
+```
+
+## What NOT to Spy On
+
+### 1. Authorization/Access Control Functions
+These are pure functions that should be tested with proper mock events:
+- `checkModule`
+- `checkWriteAccess`
+- `accessRightsUtils`
+- `getCurrentUser`
+
+### 2. Data Transformation Functions
+- `createFilters`
+- `createSort`
+- `parseBody`
+- `userDefaultBid`
+
+### 3. Internal Utility Functions
+- Pure functions that don't have side effects
+- Data formatting functions
+- Validation functions
+
+## Event Mock Pattern
+
+Create comprehensive event mocks instead of spying on auth functions:
+
+```javascript
+const mockEvent = {
+    body: {
+        businessId: 'ABC',
+        amount: 100,
+        customerId: 1,
+        // ... other required fields
+    },
+    pathParameters: {
+        id: 1
+    },
+    queryStringParameters: {
+        businessId: 'ABC',
+        limit: '10',
+        offset: '0'
+    },
+    requestContext: {
+        authorizer: {
+            claims: {
+                'custom:AR': JSON.stringify({ 
+                    businessIds: { 'ABC': 'A' }, 
+                    module: { 
+                        payment: { read: true, write: true }
+                    } 
+                })
+            }
+        }
+    },
+    headers: {
+        Authorization: 'Bearer mock-jwt-token'
+    }
+};
+```
+
+## Spy Pattern Guidelines
+
+### 1. Create Spies Inline
+```javascript
+it('should handle database failure', async () => {
+    // Create spies specific to this test
+    const paymentFindSpy = spyOn(Payment, 'findOne').and.returnValue(Promise.reject(new Error('DB Error')));
+    const auditSpy = spyOn(audit, 'attach').and.returnValue(Promise.resolve());
+    
+    const result = await getPayment(mockEvent);
+    
+    expect(result.statusCode).toBe(500);
+    expect(paymentFindSpy).toHaveBeenCalled();
+    expect(auditSpy).toHaveBeenCalled();
+});
+```
+
+### 2. Use Descriptive Spy Names
+```javascript
+const paymentCreateSpy = spyOn(Payment, 'create');
+const sendEmailSpy = spyOn(inboxUtils, 'sendEmailToInbox');
+const webhookSpy = spyOn(webhookUtils, 'sendToWebhook');
+```
+
+### 3. Control Test Flow with Return Values
+```javascript
+// Success case
+spyOn(Payment, 'findOne').and.returnValue(Promise.resolve(mockPayment));
+
+// Failure case
+spyOn(Payment, 'findOne').and.returnValue(Promise.reject(new Error('Not found')));
+
+// Null/empty case
+spyOn(Payment, 'findOne').and.returnValue(Promise.resolve(null));
+```
+
+### 4. Mock Complex Objects Properly
+```javascript
+const mockPayment = {
+    id: 1,
+    status: 'Open',
+    amount: 100,
+    toJSON: () => ({
+        id: 1,
+        status: 'Open',
+        amount: 100,
+        customer: { contacts: [] }
+    }),
+    set: () => {},
+    save: () => Promise.resolve(),
+    get: () => {}
+};
+```
+
+### 5. Verify Spy Calls When Necessary
+```javascript
+// Verify the spy was called
+expect(webhookSpy).toHaveBeenCalled();
+
+// Verify specific arguments
+expect(webhookSpy).toHaveBeenCalledWith(1, 'hookRef', webhookTypes.paymentCreated, jasmine.any(Object));
+
+// Verify call count
+expect(emailSpy).toHaveBeenCalledTimes(1);
+
+// Get call details
+const lastCall = webhookSpy.calls.mostRecent();
+expect(lastCall.args[2].type).toBe('paymentCreated');
+```
+
+## Key Principles
+
+1. **Self-Contained Tests**: Each test should have its own spies, not shared in beforeEach
+2. **Minimal Spying**: Only spy on what's necessary for the specific test scenario
+3. **External Boundaries**: Only mock external dependencies (DB, network, file system)
+4. **No Lodash Get**: Use optional chaining or destructuring instead
+5. **No Nested Ternaries**: Use if/else statements for clarity
+6. **No beforeEach**: Define all test setup inline within each test
+
+## Example Test Structure
+
+```javascript
+describe('paymentRoutes', () => {
+    describe('createPayment', () => {
+        it('should successfully create a payment', async () => {
+            // Arrange - Create spies for external dependencies
+            const auditSpy = spyOn(audit, 'attach').and.returnValue(Promise.resolve());
+            const paymentCreateSpy = spyOn(Payment, 'create').and.returnValue(Promise.resolve({ id: 1 }));
+            const paymentFindSpy = spyOn(Payment, 'findOne').and.returnValue(Promise.resolve(mockPayment));
+            const webhookSpy = spyOn(webhookUtils, 'sendToWebhook').and.returnValue(Promise.resolve());
+            
+            // Arrange - Create mock event
+            const mockEvent = {
+                body: { amount: 100, customerId: 1 },
+                requestContext: {
+                    authorizer: {
+                        claims: {
+                            'custom:AR': JSON.stringify({ 
+                                businessIds: { 'ABC': 'A' },
+                                module: { payment: { write: true } }
+                            })
+                        }
+                    }
+                }
+            };
+            
+            // Act
+            const result = await createPaymentFromRoute(mockEvent);
+            
+            // Assert
+            expect(result.statusCode).toBe(200);
+            expect(paymentCreateSpy).toHaveBeenCalled();
+            expect(webhookSpy).toHaveBeenCalledWith(
+                1,
+                jasmine.any(String),
+                webhookTypes.paymentCreated,
+                jasmine.any(Object)
+            );
+        });
+        
+        it('should handle database transaction failure', async () => {
+            // Arrange - Mock transaction failure
+            const transactionMock = {
+                commit: jasmine.createSpy('commit'),
+                rollback: jasmine.createSpy('rollback')
+            };
+            spyOn(db, 'getConnection').and.returnValue({
+                transaction: () => transactionMock
+            });
+            spyOn(Payment, 'create').and.returnValue(Promise.reject(new Error('DB Error')));
+            
+            // Arrange - Create mock event
+            const mockEvent = {
+                body: { amount: 100 },
+                requestContext: {
+                    authorizer: {
+                        claims: {
+                            'custom:AR': JSON.stringify({ 
+                                businessIds: { 'ABC': 'A' },
+                                module: { payment: { write: true } }
+                            })
+                        }
+                    }
+                }
+            };
+            
+            // Act
+            const result = await createPaymentFromRoute(mockEvent);
+            
+            // Assert
+            expect(result.statusCode).toBe(500);
+            expect(transactionMock.rollback).toHaveBeenCalled();
+            expect(transactionMock.commit).not.toHaveBeenCalled();
+        });
+    });
+});
+```
+
+## Common Patterns to Follow
+
+1. **Database Mock Pattern**:
+   - Always include required methods like `toJSON()`, `set()`, `save()`, `get()`
+   - Return promises for async operations
+
+2. **Error Testing Pattern**:
+   - Test both rejection and null returns
+   - Verify proper error codes and messages
+
+3. **Transaction Pattern**:
+   - Mock both commit and rollback
+   - Verify rollback on failure, commit on success
+
+4. **External Service Pattern**:
+   - Mock the exact response structure expected
+   - Test both success and failure scenarios
+
+5. **Webhook Pattern**:
+   - Verify webhook type and payload structure
+   - Check that webhooks are sent at appropriate times