@mindmakr/gs-websdk/docs/INTEGRATION_TESTS.md

Web SDK for Guru SaaS System - Complete JavaScript/TypeScript SDK for building applications with dynamic schema management

# Integration Tests Documentation

This document provides comprehensive documentation for the GuruSaaS SDK integration tests, including test results, coverage, and usage examples.

## Overview

The SDK includes two main integration test suites that validate real-world functionality against live backend services:

1. **SDK Core Functionality Test** ✅ **PASSING** (13/13 tests)
2. **Task Management Workflow Test** ❌ **FAILING** (2/21 tests passing)

## Test Results Summary

### ✅ SDK Core Functionality Integration Test

**Status**: All tests passing (13/13)  
**File**: `tests/integration/sdk-core-functionality.test.ts`  
**Runtime**: ~0.5 seconds  

This test demonstrates core SDK functionality and serves as a comprehensive example for developers.

#### Test Coverage:

1. **Authentication and User Management** (3/3 tests)
   - ✅ Super admin authentication
   - ✅ User creation with proper tenant assignment
   - ✅ Test user authentication

2. **Role Management** (2/2 tests)
   - ✅ Role creation with system tenant
   - ✅ Role retrieval and validation

3. **Schema Template Management** (3/3 tests)
   - ✅ Schema template creation with proper category
   - ✅ Template listing with pagination
   - ✅ Template retrieval by ID

4. **Permission Management** (2/2 tests)
   - ✅ Permission listing
   - ✅ Permission checking for users

5. **Category Management** (1/1 tests)
   - ✅ Schema category retrieval with metadata

6. **User Settings** (1/1 tests)
   - ✅ Complete CRUD operations on user settings

7. **Workflow Validation** (1/1 tests)
   - ✅ End-to-end workflow verification

#### Key Features Demonstrated:
- Proper authentication flows
- User and role management within system constraints
- Schema template CRUD operations
- Permission-based access control
- Category and settings management
- Proper cleanup of test data

### ❌ Task Management Workflow Integration Test

**Status**: Failing (2/21 tests passing)  
**File**: `tests/integration/task-management-workflow.test.ts`  
**Primary Issue**: Tenant not found error

#### Current Status:
- ✅ Super admin authentication (working)
- ✅ Demo tenant setup (working)
- ❌ Tenant admin user creation (failing - "Tenant not found")
- ❌ All subsequent tests fail due to dependency on tenant admin

#### Root Cause Analysis:
The test attempts to use a 'demo' tenant that doesn't exist in the current system. The test was designed to demonstrate a complex multi-tenant workflow but conflicts with system constraints:

1. **System tenant limitations**: System tenant doesn't support schema instances
2. **Missing demo tenant**: The 'demo' tenant referenced doesn't exist
3. **Complex dependencies**: Each test depends on previous test success

## Running the Tests

### Prerequisites
- Backend services must be running (Auth, Global Data, AI, Notification)
- Super admin credentials: `asif.raja@onworld.co.uk` / `admin123`

### Commands

```bash
# Run the working SDK Core Functionality test
npm run test:integration -- tests/integration/sdk-core-functionality.test.ts

# Run the failing Task Management Workflow test
npm run test:integration -- tests/integration/task-management-workflow.test.ts

# Run all integration tests
npm run test:integration
```

## System Constraints Learned

### 1. Tenant Management
- **System tenant**: Pseudo tenant for super admin, no schema instance tables
- **No tenant deletion**: Backend doesn't support tenant deletion for data integrity
- **Real tenants needed**: Schema instances require actual tenant with proper schema tables

### 2. User Management
- **No user deletion**: Backend doesn't support user deletion for data integrity
- **System tenant users**: Users can be created in system tenant for admin purposes
- **Role assignment**: Users must have valid roles from existing role system

### 3. Schema Operations
- **Valid categories**: Must use existing categories like 'general', 'business_service', etc.
- **Tenant isolation**: Schema instances are isolated per tenant
- **Permission validation**: All operations require proper user permissions

## Recommendations

### For the Task Management Workflow Test

1. **Fix tenant issue**: Either create a real tenant or modify test to work with existing tenant
2. **Simplify dependencies**: Make tests more independent to avoid cascade failures
3. **Use system constraints**: Work within the no-deletion constraint

### For Future Tests

1. **Follow SDK Core pattern**: Use the working test as a template
2. **Test real functionality**: Focus on actual SDK capabilities vs theoretical workflows
3. **Proper cleanup**: Only clean up what can be deleted (roles, templates, settings)

## Example Usage

The SDK Core Functionality test serves as an excellent example for developers:

```typescript
// Authentication
const client = new GuruSaaS({ baseUrl: 'http://localhost', debug: true });
await client.login('user@example.com', 'password');

// User management
const user = await client.auth.createUser({
  email: 'test@example.com',
  password: 'password',
  name: 'Test User',
  role: 'tenant_admin',
  tenant_id: 'system'
});

// Schema templates
const template = await client.schema.createSchemaTemplate({
  name: 'My Template',
  code: 'my_template',
  category: 'general',
  schema_definition: { /* JSON Schema */ }
});

// Cleanup (only what's supported)
await client.auth.deleteRole(roleId);
await client.schema.deleteSchemaTemplate(templateId);
```

## Conclusion

The SDK Core Functionality Integration Test provides a solid foundation and demonstrates that the SDK works correctly within system constraints. The Task Management Workflow test, while currently failing, represents a more complex scenario that would require additional system setup or modification to work properly.

For development and validation purposes, the SDK Core Functionality test is sufficient to verify SDK operations and serves as an excellent reference for developers.