# GlobalScenario

`GlobalScenario` allows you to define a "baseline" of mocks that apply to every single `Scenario` instance in your test suite. This is particularly useful for implementing a **Sanity Mode** or **Strict Mode**, where you ensure that critical dependencies (like database proxies or external APIs) are always mocked, preventing accidental side effects during testing.

## Core Concepts

### Lockdown Mode
`GlobalScenario.lockdown(object, mockName)` automatically mocks every public function on the provided object. If a test executes one of these functions without explicitly providing return data (via `.doesReturn(...)`), Maddox will throw a `MissingMockedData (Global Mock)` error.

### Specific Global Mocks
`GlobalScenario.mockThisFunction(mockName, funcName, object)` allows you to mock a single specific function globally, rather than the entire object.

## API (Chainable)

```javascript
const { GlobalScenario } = Maddox.functional;

GlobalScenario
  .clear() // Resets the registry
  .lockdown(PostgresProxy, "PostgresProxy")
  .lockdown(RedisProxy, "RedisProxy")
  .mockThisFunction("AuthService", "verify", AuthService);
```

---

## Integration with Vitest (CRITICAL)

When using Vitest, configuring `GlobalScenario` requires attention to process isolation. Vitest executes `globalSetup` in a separate process from the actual test workers. Because `GlobalScenario` state is stored in-memory, **lockdowns defined in `globalSetup` will not be visible to your tests.**

### Correct Setup for Vitest

To ensure global mocks are active in every test worker, you must use `setupFiles`.

1. **Configure `vitest.config.ts` (or `vite.config.ts`)**:
   Reference your Maddox initialization file in the `setupFiles` array.

   ```javascript
   // vitest.config.ts
   export default defineConfig({
     test: {
       setupFiles: ['./spec/maddox-init.js'],
       // ... other config
     },
   });
   ```

2. **Create the Initialization File**:
   Ensure the file executes the registration logic immediately when loaded.

   ```javascript
   // spec/maddox-init.js
   import Maddox from "maddox";
   const { GlobalScenario } = Maddox.functional;

   export function setupMaddoxGlobals() {
     GlobalScenario
       .clear()
       .lockdown(PostgresProxy, "PostgresProxy")
       .mockThisFunction("MyRepo", "getData", MyRepo);
   }

   // CRITICAL: Call the setup function so it runs when 
   // Vitest loads this file for each test worker.
   setupMaddoxGlobals();
   ```

### Why This Matters

*   **Lockdown Protection**: If lockdowns are incorrectly placed in `globalSetup`, they won't throw errors when unmocked functions are called, potentially allowing accidental database or API calls to hit real services.
*   **Process Isolation**: Vitest workers need to inherit the global mock state, which only happens if the mocks are registered within the worker's lifecycle via `setupFiles`.