2025-12-11 22:50:18 +08:00

26 KiB

Raw Blame History

Design Document

Overview

This document outlines the comprehensive testing strategy for the overseas appointment backend admin management system. The testing approach combines automated integration tests, property-based tests, and manual testing procedures to ensure all admin functionalities work correctly and securely.

The admin system consists of multiple modules:

Authentication and RBAC
User management
Appointment management
Withdrawal review
Service and category management
Statistics dashboard
System configuration
Home content management
Translation management
File upload
Security and validation

Architecture

Testing Architecture

┌─────────────────────────────────────────────────────────┐
│                   Test Suite                             │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────────┐  ┌──────────────────┐            │
│  │  Integration     │  │  Property-Based  │            │
│  │  Tests           │  │  Tests           │            │
│  │  (Jest+Supertest)│  │  (fast-check)    │            │
│  └────────┬─────────┘  └────────┬─────────┘            │
│           │                     │                       │
│           └──────────┬──────────┘                       │
│                      │                                  │
│           ┌──────────▼──────────┐                       │
│           │   Test Database     │                       │
│           │   (MySQL)           │                       │
│           └─────────────────────┘                       │
│                                                          │
│  ┌──────────────────────────────────────────┐           │
│  │  Manual Test Procedures                  │           │
│  │  (Documented test cases)                 │           │
│  └──────────────────────────────────────────┘           │
│                                                          │
└─────────────────────────────────────────────────────────┘

Test Data Management

Use test database with isolated data
Create test fixtures for admins with different roles
Generate random test data using fast-check generators
Clean up test data after each test suite

Components and Interfaces

Test Utilities

AdminTestHelper

Purpose: Helper functions for admin testing
Methods:
- createTestAdmin(role, status): Create test admin account
- loginAsAdmin(username, password): Login and get token
- makeAuthenticatedRequest(token, method, path, data): Make authenticated API call
- cleanupTestData(): Remove test data

DataGenerators

Purpose: Generate random test data using fast-check
Generators:
- adminCredentials(): Generate valid admin credentials
- userSearchCriteria(): Generate user search parameters
- appointmentData(): Generate appointment test data
- serviceData(): Generate service with translations
- dateRange(): Generate valid date ranges

ResponseValidator

Purpose: Validate API response formats
Methods:
- validateSuccessResponse(response): Check success response structure
- validateErrorResponse(response, expectedCode): Check error response
- validatePaginationResponse(response): Check pagination structure

Test Suites

Authentication Test Suite

Tests admin login flow
Validates JWT token generation
Checks login history recording
Verifies token validation

RBAC Test Suite

Tests role-based access control
Validates permission boundaries
Checks role hierarchy

CRUD Test Suites (for each resource)

User management tests
Appointment management tests
Withdrawal management tests
Service management tests
Category management tests
Configuration management tests
Home content management tests

Integration Test Suites

End-to-end workflows
Cross-module interactions
Data consistency checks

Data Models

Test Admin Model

{
  id: UUID,
  username: string,
  password: string (hashed),
  email: string,
  role: 'super_admin' | 'admin' | 'operator',
  status: 'active' | 'inactive',
  createdAt: timestamp,
  updatedAt: timestamp,
  lastLoginAt: timestamp
}

Test Response Format

// Success Response
{
  success: true,
  data: {
    // Response data
  },
  meta: {
    // Optional metadata (pagination, etc.)
  }
}

// Error Response
{
  success: false,
  error: {
    code: string,
    message: string,
    details: object (optional)
  }
}

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Authentication Properties

Property 1: Valid login returns token and profile For any valid admin credentials, logging in should return a JWT token and admin profile without the password field Validates: Requirements 1.1

Property 2: Invalid credentials are rejected For any invalid credentials (wrong username, wrong password, or both), login attempts should be rejected with error code INVALID_CREDENTIALS Validates: Requirements 1.2

Property 3: Login creates history record For any successful admin login, a login history record should be created with timestamp, IP address, and user agent Validates: Requirements 1.4

Property 4: Valid tokens grant access For any valid admin JWT token, requests to protected endpoints should be granted access Validates: Requirements 1.5

Property 5: Invalid tokens are rejected For any invalid or malformed JWT token, requests should be rejected with error code INVALID_TOKEN Validates: Requirements 1.6

RBAC Properties

Property 6: Super admin has full access For any endpoint in the system, a super_admin token should grant access Validates: Requirements 2.1

Property 7: Admin inherits operator permissions For any operator-level endpoint, an admin token should grant access Validates: Requirements 2.2

Property 8: Admin cannot access super admin endpoints For any super_admin-only endpoint, an admin token should be rejected with error code FORBIDDEN Validates: Requirements 2.3

Property 9: Operator has limited access For any operator-level endpoint, an operator token should grant access Validates: Requirements 2.4

Property 10: Operator cannot escalate privileges For any admin or super_admin endpoint, an operator token should be rejected with error code FORBIDDEN Validates: Requirements 2.5

User Management Properties

Property 11: Pagination returns correct counts For any page number and page size, the user list should return the correct subset of users and accurate total count Validates: Requirements 3.1

Property 12: Search returns only matching users For any search criteria, all returned users should match the search parameters Validates: Requirements 3.2

Property 13: User status updates persist For any user and status value, updating the status then retrieving the user should reflect the new status Validates: Requirements 3.3

Property 14: User details are complete For any user ID, the user details response should include all required fields including appointments and invitations Validates: Requirements 3.4

Property 15: Date filtering is accurate For any date range, all returned users should have creation dates within that range Validates: Requirements 3.5

Appointment Management Properties

Property 16: Appointments include related data For any appointment list request, all appointments should include user and service details Validates: Requirements 4.1

Property 17: Status filtering works correctly For any appointment status, filtering by that status should return only appointments with that status Validates: Requirements 4.2

Property 18: Appointment status updates persist For any appointment and status value, updating the status then retrieving the appointment should reflect the new status and updated timestamp Validates: Requirements 4.3

Property 19: Appointment search returns matches For any search query (user or service), all returned appointments should match the search criteria Validates: Requirements 4.4

Property 20: Appointment details are complete For any appointment ID, the details response should include all required appointment information Validates: Requirements 4.5

Withdrawal Management Properties

Property 21: Pending filter returns only pending For any withdrawal list filtered by pending status, all returned withdrawals should have status pending Validates: Requirements 5.1

Property 22: Approval updates status and records admin For any withdrawal, approving it should update status to approved and record the admin ID Validates: Requirements 5.2

Property 23: Rejection updates status and records reason For any withdrawal and rejection reason, rejecting it should update status to rejected and store the reason Validates: Requirements 5.3

Property 24: Withdrawal history includes user data For any withdrawal history request, all withdrawals should include user information Validates: Requirements 5.4

Property 25: Withdrawal date filtering is accurate For any date range, all returned withdrawals should fall within that period Validates: Requirements 5.5

Service Management Properties

Property 26: Service creation persists all languages For any service data with multi-language fields, creating the service then retrieving it should return all language versions Validates: Requirements 6.1

Property 27: Service updates persist all changes For any service and update data, updating the service then retrieving it should reflect all changes including translations Validates: Requirements 6.2

Property 28: Service deletion removes record For any service, deleting it then attempting to retrieve it should return not found Validates: Requirements 6.3

Property 29: Image upload returns accessible URL For any valid image file, uploading it should return a URL that can be accessed to retrieve the image Validates: Requirements 6.4

Property 30: Service list includes categories For any service list request, all services should include their category information Validates: Requirements 6.5

Category Management Properties

Property 31: Category creation persists all languages For any category data with multi-language names, creating the category then retrieving it should return all language versions Validates: Requirements 7.1

Property 32: Category translation updates persist For any category and translation updates, updating translations then retrieving the category should reflect all language changes Validates: Requirements 7.2

Property 33: Category deletion respects references For any category with no service references, deleting it should remove the category; for categories with services, deletion should fail Validates: Requirements 7.3

Property 34: Category list includes service counts For any category list request, each category's service count should match the actual number of services in that category Validates: Requirements 7.4

Property 35: Category reordering persists For any new category order, updating the order then retrieving categories should reflect the new sequence Validates: Requirements 7.5

Statistics Properties

Property 36: Overview statistics are accurate For any time period, overview statistics counts should match actual database records for users, appointments, and revenue Validates: Requirements 8.1

Property 37: User growth aggregation is correct For any date range, user growth data should correctly aggregate user registrations by time period Validates: Requirements 8.2

Property 38: Appointment statistics match reality For any time period, appointment status distribution should match actual appointment records Validates: Requirements 8.3

Property 39: Revenue calculations are accurate For any time period, revenue statistics should match the sum of actual transaction amounts Validates: Requirements 8.4

Property 40: Statistics date filtering works For any date range, statistics should only include data from that period Validates: Requirements 8.5

Configuration Properties

Property 41: Config retrieval is complete For any config retrieval request, all config key-value pairs should be returned Validates: Requirements 9.1

Property 42: Config updates persist immediately For any config key and value, updating the config then retrieving it should return the new value Validates: Requirements 9.2

Property 43: Batch config updates are atomic For any set of config updates, either all updates should succeed or none should be applied Validates: Requirements 9.3

Property 44: Single config retrieval works For any config key, retrieving by key should return the correct value Validates: Requirements 9.4

Property 45: Config caching is consistent For any config key, multiple reads should return the same value without database queries Validates: Requirements 9.5

Home Content Properties

Property 46: Banner creation persists data For any banner data, creating the banner then retrieving it should return the same image URL and display order Validates: Requirements 10.1

Property 47: Banner reordering persists For any new banner order, updating the order then retrieving banners should reflect the new sequence Validates: Requirements 10.2

Property 48: Banner deletion removes record For any banner, deleting it then attempting to retrieve it should return not found Validates: Requirements 10.3

Property 49: Hot service addition persists For any service and display order, adding it as a hot service then retrieving hot services should include it Validates: Requirements 10.4

Property 50: Hot service removal works For any hot service, removing it then retrieving hot services should not include it Validates: Requirements 10.5

Translation Properties

Property 51: Language translations are complete For any supported language, retrieving translations should return all key-value pairs for that language Validates: Requirements 11.1

Property 52: Translation updates persist For any translation key, language, and value, updating the translation then retrieving it should return the new value Validates: Requirements 11.2

Property 53: New keys create all language entries For any new translation key, adding it should create entries for all supported languages (zh, en, pt) Validates: Requirements 11.3

Property 54: Language negotiation works For any Accept-Language header value, the system should return content in the matching language Validates: Requirements 11.4

Property 55: Translation fallback works For any missing translation, the system should return the default language version Validates: Requirements 11.5

File Upload Properties

Property 56: Valid image upload succeeds For any valid image file (jpg, png, webp), uploading should store the file and return an accessible public URL Validates: Requirements 12.1

Property 57: Invalid file types are rejected For any non-image file type, upload attempts should be rejected with an appropriate error Validates: Requirements 12.2

Property 58: Multiple file upload works For any set of valid image files, uploading them should process all files and return URLs for each Validates: Requirements 12.4

Property 59: File serving has correct headers For any uploaded file URL, accessing it should return the file with correct Content-Type header Validates: Requirements 12.5

Response Format Properties

Property 60: Success responses are consistent For any successful API endpoint, the response should have success: true and a data object Validates: Requirements 13.1

Property 61: Error responses are consistent For any failed API endpoint, the response should have success: false and an error object with code and message Validates: Requirements 13.2

Property 62: Validation errors have details For any validation failure, the error response should have code VALIDATION_ERROR and include validation details Validates: Requirements 13.3

Property 63: Auth errors have correct codes For any authentication failure, the error response should have an appropriate auth error code (MISSING_TOKEN, INVALID_TOKEN, etc.) Validates: Requirements 13.4

Property 64: Server errors are formatted correctly For any server error, the response should have code INTERNAL_ERROR and an error message Validates: Requirements 13.5

Logging Properties

Property 65: Operations are logged For any admin operation, a log entry should be created with admin ID and timestamp Validates: Requirements 14.1

Property 66: Sensitive data is redacted For any operation that modifies data, the log should include request body with passwords and secrets redacted Validates: Requirements 14.2

Property 67: Request metadata is logged For any admin request, the log should include IP address and user agent Validates: Requirements 14.3

Property 68: Response status is logged For any completed operation, the log should include the response status code Validates: Requirements 14.4

Property 69: Errors are logged with details For any error that occurs, the log should include error details for debugging Validates: Requirements 14.5

Security Properties

Property 70: SQL injection is prevented For any input containing SQL injection attempts, the system should sanitize the input and prevent execution Validates: Requirements 15.2

Property 71: XSS payloads are sanitized For any text input containing XSS payloads, the system should sanitize and escape dangerous content Validates: Requirements 15.3

Property 72: CORS policies are enforced For any cross-origin request, the system should enforce proper CORS policies based on configuration Validates: Requirements 15.5

Error Handling

Error Response Format

All errors follow the standardized format:

{
  success: false,
  error: {
    code: string,      // Machine-readable error code
    message: string,   // Human-readable error message
    details: object    // Optional additional error details
  }
}

Error Codes

Code	HTTP Status	Description
MISSING_CREDENTIALS	400	Username or password not provided
INVALID_CREDENTIALS	401	Wrong username or password
ACCOUNT_INACTIVE	403	Admin account is inactive
MISSING_TOKEN	401	No authentication token provided
INVALID_TOKEN	401	Token is invalid or expired
INVALID_TOKEN_TYPE	401	Wrong token type for endpoint
FORBIDDEN	403	Insufficient permissions
VALIDATION_ERROR	400	Input validation failed
NOT_FOUND	404	Resource not found
INTERNAL_ERROR	500	Server error occurred
INVALID_JSON	400	Malformed JSON in request

Error Handling Strategy

Validation Errors: Catch at controller level, return detailed validation errors
Authentication Errors: Handle in auth middleware, return appropriate auth error codes
Authorization Errors: Handle in RBAC middleware, return FORBIDDEN
Database Errors: Catch in service layer, log details, return generic error to client
Unexpected Errors: Catch in global error handler, log full stack trace, return INTERNAL_ERROR

Testing Strategy

Unit Testing

Unit tests focus on individual functions and modules:

Authentication utilities: Token generation, validation, password hashing
RBAC logic: Permission checking, role hierarchy
Data validators: Input validation functions
Response formatters: Success/error response builders
Generators: Test data generation functions

Property-Based Testing

Property-based tests use fast-check to verify properties across many random inputs:

Testing Framework: Jest with fast-check
Iterations: Minimum 100 iterations per property
Generators: Custom generators for admin data, credentials, search criteria, etc.
Shrinking: Automatic test case minimization on failure
Tagging: Each property test tagged with format: **Feature: admin-system-comprehensive-test, Property {number}: {property_text}**

Property Test Structure:

describe('Property: {property description}', () => {
  it('should hold for all valid inputs', () => {
    fc.assert(
      fc.property(
        // Generators
        fc.record({
          username: fc.string(),
          password: fc.string()
        }),
        // Test function
        async (credentials) => {
          // Test logic
          const response = await loginAdmin(credentials);
          // Assertions
          expect(response).toMatchProperty();
        }
      ),
      { numRuns: 100 }
    );
  });
});

Integration Testing

Integration tests verify end-to-end workflows:

Test Database: Isolated MySQL test database
Test Data: Created before each test suite, cleaned after
API Testing: Using supertest to make HTTP requests
Authentication: Login once, reuse token for test suite
Assertions: Verify database state, response format, side effects

Integration Test Structure:

describe('Admin User Management Integration', () => {
  let adminToken;
  
  beforeAll(async () => {
    await setupTestDatabase();
    adminToken = await loginAsTestAdmin();
  });
  
  afterAll(async () => {
    await cleanupTestDatabase();
  });
  
  test('should list users with pagination', async () => {
    const response = await request(app)
      .get('/api/v1/admin/users?page=1&limit=10')
      .set('Authorization', `Bearer ${adminToken}`);
      
    expect(response.status).toBe(200);
    expect(response.body.success).toBe(true);
    expect(response.body.data.users).toBeInstanceOf(Array);
    expect(response.body.meta.total).toBeGreaterThan(0);
  });
});

Manual Testing

Manual test procedures for scenarios that are difficult to automate:

UI Testing: Admin portal interface testing
File Upload: Test various file types and sizes
Performance: Load testing with many concurrent requests
Security: Penetration testing for vulnerabilities
Cross-browser: Test admin portal in different browsers

Manual Test Documentation:

Step-by-step test procedures
Expected results for each step
Screenshots for UI tests
Test data requirements
Environment setup instructions

Test Coverage Goals

Unit Tests: 80%+ code coverage
Integration Tests: All API endpoints covered
Property Tests: All correctness properties implemented
Manual Tests: Critical user workflows documented

Test Execution

# Run all tests
npm test

# Run specific test suite
npm test -- admin-auth.test.js

# Run with coverage
npm test -- --coverage

# Run property tests only
npm test -- --testNamePattern="Property:"

# Run integration tests only
npm test -- --testNamePattern="Integration"

Continuous Integration

Run all tests on every commit
Fail build if any test fails
Generate coverage reports
Run security scans
Performance benchmarks

Implementation Notes

Test Data Management

Fixtures: Pre-defined test data for common scenarios
Factories: Functions to create test data with defaults
Generators: fast-check generators for random test data
Cleanup: Automatic cleanup after each test suite

Database Isolation

Use separate test database
Reset database before each test suite
Use transactions for test isolation where possible
Clean up test data after tests complete

Authentication in Tests

Create test admin accounts with different roles
Login once per test suite to get token
Reuse token for multiple tests
Test token expiration separately

Mocking Strategy

Avoid mocking for integration tests - test real implementations
Mock external services: WeChat API, payment gateways, email services
Mock time: For testing time-dependent features
Mock file system: For file upload tests when needed

Performance Considerations

Run tests in parallel where possible
Use database transactions for faster cleanup
Cache test data that doesn't change
Skip slow tests in development, run in CI

Security Considerations

Test Security

Never commit real credentials to test files
Use environment variables for test configuration
Sanitize test logs to remove sensitive data
Secure test database access

Security Testing

Test SQL injection prevention
Test XSS prevention
Test CSRF protection
Test rate limiting
Test authentication bypass attempts
Test authorization escalation attempts

Monitoring and Reporting

Test Reports

Generate HTML test reports
Track test execution time
Monitor test flakiness
Report coverage trends

Failure Analysis

Capture screenshots on UI test failures
Log full request/response on API test failures
Save database state on integration test failures
Provide reproduction steps for failures

Future Enhancements

Visual regression testing for admin UI
Performance benchmarking suite
Chaos engineering tests
Accessibility testing
Mobile responsiveness testing
Internationalization testing

26 KiB Raw Blame History

Design Document

Overview

Architecture

Testing Architecture

Test Data Management

Components and Interfaces

Test Utilities

Test Suites

Data Models

Test Admin Model

Test Response Format

Correctness Properties

Authentication Properties

RBAC Properties

User Management Properties

Appointment Management Properties

Withdrawal Management Properties

Service Management Properties

Category Management Properties

Statistics Properties

Configuration Properties

Home Content Properties

Translation Properties

File Upload Properties

Response Format Properties

Logging Properties

Security Properties

Error Handling

Error Response Format

Error Codes

Error Handling Strategy

Testing Strategy

Unit Testing

Property-Based Testing

Integration Testing

Manual Testing

Test Coverage Goals

Test Execution

Continuous Integration

Implementation Notes

Test Data Management

Database Isolation

Authentication in Tests

Mocking Strategy

Performance Considerations

Security Considerations

Test Security

Security Testing

Monitoring and Reporting

Test Reports

Failure Analysis

Future Enhancements

26 KiB

Raw Blame History