# Testing Documentation

Tobuzz Extractor maintains a fast, deterministic test suite using Node.js native test runner (`node --test`). Tests do not depend on external network calls by default.

---

## Test Hierarchy

### 1. Deterministic Unit & Fixture Tests
Run as part of `npm test`:

- **`tests/request.test.ts`**: Verifies path parsing (`/api/resolve/{tmdbId}` and `/api/resolve/{tmdbId}/{season}/{episode}`), TMDB ID validation, and provider filters (`only`, `exclude`, `provider`, `providers`).
- **`tests/resolver.test.ts`**: Verifies provider orchestration, fallback logic, request timeouts, error capture, attempt recording, and player iframe URL rejection.
- **`tests/validation.test.ts`**: Verifies preflight media validation rules:
  - HLS `#EXTM3U` tag requirements
  - Variant & segment reachability
  - Encryption key endpoint reachability
  - Plaintext error page rejection (HTML, 401/403, "not in range")
  - Query parameter & header preservation
  - MP4 range request validation
  - Candidate ranking order
- **`tests/proxy.test.ts`**: Verifies playlist rewriting, token caching, proxy token substitution, and host allowlist security (`isApprovedMediaHost`).
- **`tests/vidnest.test.ts`**: Verifies VidNest multi-server fallback, Base64 custom alphabet decryption, and audio language tier sorting.
- **`tests/vidsrcsu.test.ts`**: Verifies Vidsrc.su path construction, nonce generation, HMAC request signing, and WebAssembly decryption.
- **`tests/vidsrcto.test.ts`**: Verifies Vidsrc.to iframe navigation, WebAssembly ChaCha20 cipher decryption, stream host token generation, and proxy URL wrapping.
- **`tests/api.test.ts`**: Verifies API endpoint handlers, HTTP status codes, error payloads, and query merging.

### 2. Live Network Integration Tests (Opt-In)
Included in `tests/live_resolver.test.ts`. These tests make real network calls against upstream providers to verify end-to-end resolution.

To run live integration tests:
```bash
RUN_LIVE_TESTS=1 npm test
```

Specific provider live test flags:
```bash
# Live Vidsrc.to test
RUN_LIVE_VIDSRC=1 npm test

# Live Cinejoy test (if enabled)
RUN_LIVE_CINEJOY=1 npm test
```

---

## Verification Standard: Extracted vs Validated vs Playable

When evaluating provider functionality or writing tests:

1. **Extracted**: The provider successfully obtained a media candidate URL from an upstream API/iframe/WASM.
2. **Validated**: Tobuzz Extractor's validation engine probed the master playlist, variant playlist, segment, or key, confirming HTTP 200/206 status, correct Content-Type, and absence of HTML/auth error pages.
3. **Playable**: The final normalized URL (direct or proxied) can be loaded and played continuously in an HLS-capable video player.

A test is only considered passing when the returned source achieves **Validated** status.

---

## Running Test Commands

```bash
# Typecheck TypeScript files
npm run typecheck

# Run full test suite
npm test

# Run tests in watch mode / specific file
node --test dist/tests/vidnest.test.js
```