Testing & Verification

Testing and verification for the Financial Freedom Adventure (FinQuest AI) ensure that the core financial logic, AI-driven personas, and gamification mechanics function reliably under various network and user conditions.

Verification Strategy

The project employs a multi-layered testing approach:

1. Service Verification (Vitest/Jest): Validates core logic in geminiService, learningService, and memoryService.
2. Resilience Testing: Simulates API failures and edge cases to ensure the UI remains stable.
3. End-to-End (E2E) Testing (Cypress): Validates the full user journey from onboarding to financial evolution.

Service & Logic Testing

The FinMon Verification Suite (located in __tests__/geminiService.test.ts) validates that the AI agents respond correctly to financial data and maintain their programmed personas.

Functional Testing

Tests ensure that the AI correctly processes transactions and returns structured data for the UI to consume.

// Example: Verifying Budget Analysis output
test('Functional: getBudgetAnalysis returns structured data', async () => {
  const result = await getBudgetAnalysis(5000, mockTransactions);
  
  expect(result.healthScore).toBeGreaterThan(0);
  expect(result.summary).toBeDefined();
  expect(result.recommendations).toBeInstanceOf(Array);
});

Resilience & Error Handling

Tests simulate "Chaos" scenarios, such as 500 Server Errors or Network timeouts, to verify that the app provides a graceful fallback (the "Wild Error" persona) instead of crashing.

| Scenario | Expected Behavior | | :--- | :--- | | API 500 Error | Returns a default safe object with healthScore: 0. | | Network Failure | Returns a "Wild Error appeared" message to the chat UI. | | Malformed JSON | cleanJson helper strips markdown and returns a valid object. |

Persona Integrity

The suite verifies that the userLevel and FinMonState are correctly passed to the backend, ensuring the AI adopts the correct tone (e.g., Professor Ledger being "Grumpy" for Rookies vs "Respectful" for Master Tycoons).

Feature Validation (End-to-End)

E2E tests simulate real user interactions within the browser to verify feature integration.

Core Workflows Tested:

• Onboarding Flow: Verifying that local storage flags (finmon_has_onboarded) are set after the tour.
• Transaction Feedback: Ensuring that adding an expense triggers the damageBus visual feedback and updates the FinMon's HP.
• Persistent State: Validating that refreshing the page reloads the UserState (including chat history and points) from localStorage.
• Evolution Triggers: Testing if the useEvolutionLogic hook correctly triggers an EvolutionScene when budget goals are met.

Running Tests

Unit and Service Tests

To execute the Vitest verification suite:

npm run test

Manual Verification via DevTools

The application includes a DevControlPanel (internal component) for manual verification during development. This allows you to:

• Force Evolution: Manually trigger stage changes (Egg -> Baby -> Teen -> Master).
• Inject Points: Test achievement unlocking by instantly adding XP.
• Simulate Raid Damage: Manually decrease Raid Boss HP to verify win-state animations.

API Mocking Reference

When adding new services, use the following pattern to mock the Gemini API in your tests:

// Mock global fetch for API consistency
global.fetch = jest.fn();

(global.fetch as any).mockResolvedValueOnce({
  ok: true,
  json: async () => ({ 
    // Mocked Response Object
    estimatedTax: 15000,
    bracket: "22%" 
  })
});