Stalker Mock Server

A local mock implementation of the Stalker/Ministra portal API for development and end-to-end testing of IPTVnator.

Overview

The mock server speaks the same portal.php HTTP protocol as a real Stalker portal, generating deterministic fake data using @faker-js/faker seeded from the connecting MAC address. This means:

The same MAC address always returns the same data (consistent across page refreshes and test runs).
Different MAC addresses produce different datasets — use predefined scenario MACs for specific test conditions.
Data is generated once per MAC on first request and cached in memory for the server's lifetime. Restart to regenerate.

Quick Start

# Start the mock server (port 3210)
nx serve stalker-mock-server

# Or with file watching (auto-restarts on source changes)
nx run stalker-mock-server:serve-with-watch

# Or run both the mock server + Angular dev server in parallel
nx run-many --targets=serve --projects=stalker-mock-server,web

Then in IPTVnator, add a new Stalker portal:

Portal URL: http://localhost:3210/portal.php
MAC Address: one of the predefined scenarios below (or any MAC for auto-generated data)

Predefined Scenario MAC Addresses

MAC Address	Scenario	Description
`00:1A:79:00:00:01`	default	8 categories per type, 40 items each — the balanced go-to for daily dev
`00:1A:79:FF:FF:FF`	large	20 categories, 200 items each — stress-test pagination and virtual scroll
`00:1A:79:00:00:02`	series-heavy	15 series categories with 6 seasons × 10 episodes — test deep series navigation
`00:1A:79:00:00:03`	minimal	2 categories, 5 items — edge case testing (empty states, single items)
`00:1A:79:00:00:04`	is-series	60% of VOD items have `is_series=1` — tests the Ministra lazy-season flow
`00:1A:79:00:00:05`	embedded-series	50% of VOD items have embedded `series[]` arrays — tests the embedded series flow
`<any other MAC>`	auto	MAC bytes used as seed → deterministic unique dataset

Configuration

Environment Variable	Default	Description
`PORT`	`3210`	HTTP port the server listens on
`NODE_ENV`	`development`	Node environment

Utility Endpoints

Endpoint	Method	Description
`/health`	`GET`	Health check — returns `{ status: "ok" }`
`/reset`	`POST`	Clear all in-memory data and favorites (useful between test runs)

API Coverage

All endpoints are served at GET /portal.php?action=<action>&... matching the real Stalker protocol:

Action	Description
`handshake`	Returns a mock Bearer token
`do_auth`	Returns a mock user profile
`get_categories`	Category list filtered by `type` (itv/vod/series)
`get_genres`	Genre list (mirrors categories)
`get_ordered_list`	Paginated content list; if `movie_id` is present → returns seasons
`create_link`	Returns a real public HLS stream URL for playback
`favorites`	Add / remove / get favorites (in-memory, resets on restart)
`get_short_epg`	Current-and-upcoming EPG window for a channel (`ch_id`, `size`)
`get_epg_info`	Bulk EPG keyed by channel id for a requested `period` window

Cover Images

Cover images and logos use Picsum Photos (e.g. https://picsum.photos/seed/{id}/300/200). These are real images served from a CDN — no local setup required, but an internet connection is needed for images to display.

Stream URLs

create_link returns real public HLS test streams so video actually plays:

https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8
https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8
https://playertest.longtailvideo.com/adaptive/oceans/oceans.m3u8
https://playertest.longtailvideo.com/adaptive/bbbfull/bbbfull.m3u8

The stream chosen for a given item is deterministic based on the item's cmd string.

Using with Playwright E2E Tests

The Playwright config in apps/web-e2e/playwright.config.ts starts the mock server automatically alongside the Angular dev server when running e2e tests. See apps/web-e2e/src/stalker.e2e.ts for example stalker tests.

# Run all e2e tests (starts mock server automatically)
nx e2e web-e2e

# Or run only stalker-specific e2e tests
nx e2e web-e2e --grep "@stalker"

The test suite uses 00:1A:79:00:00:01 (default scenario) for most tests, and calls POST /reset in beforeEach to ensure a clean state between tests.

EPG Behavior

The mock server generates a 7-day EPG schedule for every ITV channel using 2-hour slots starting at the current UTC day boundary.

get_short_epg returns the current program and upcoming items from that schedule, limited by size
get_epg_info returns bulk data in the shape { js: { data: Record<channelId, program[]> } }
get_epg_info filters the bulk response from the current UTC day start through now + period

Architecture

See docs/architecture/stalker-mock-server.md for full implementation details.

Project Structure

apps/stalker-mock-server/
├── src/
│   ├── main.ts                            # Express bootstrap
│   └── app/
│       ├── scenarios.ts                   # MAC → scenario config mapping
│       ├── data-generator.ts              # Seeded faker data generation
│       ├── data-store.ts                  # Lazy per-MAC in-memory cache
│       └── routes/
│           ├── portal.route.ts            # /portal.php dispatcher
│           └── handlers/
│               ├── handshake.handler.ts
│               ├── do-auth.handler.ts
│               ├── get-categories.handler.ts
│               ├── get-ordered-list.handler.ts
│               ├── get-seasons.handler.ts
│               ├── create-link.handler.ts
│               ├── favorites.handler.ts
│               ├── get-epg-info.handler.ts
│               ├── get-short-epg.handler.ts
│               └── get-genres.handler.ts
├── project.json
├── tsconfig.json
└── README.md

6.2 KiB Raw Blame History Unescape Escape