How bismarckssr/playscopa-stress-tester works
Project Type and Purpose
• This is an open-source command-line stress-testing tool that simulates many concurrent WebSocket clients against a remote Playscopa server.
• It is not a full-stack web app; it is primarily a concurrency-driven client simulator.
File Structure
• Top-level:
• .env.example / .env → environment configuration
• pyproject.toml, requirements.txt → Python packaging & dependencies
• src/ → application code
• tests/ → unit tests
• .github/workflows/ci.yml → CI pipeline
• src/ breakdown:
• config.py → loads .env into config objects
• client.py → StressClient class (listener loop, sender tasks, asyncio.Events)
• main.py → entry point; reads config, spins up clients under asyncio.TaskGroup
Key Architecture Insights from README
• Async I/O pattern: each virtual client runs two coroutines (listener + sender) synchronized via events.
• External dependency: the remote WebSocket server (Playscopa).
• Configurable parameters: server URL, number of clients, test duration.
Main Components
a. Config Loader
• Loads .env → exposes WEBSOCKET_URL, STRESSER_SESSIONS, etc.
b. Orchestrator (main application)
• Reads config → creates an asyncio.TaskGroup
• Launches N instances of StressClient
c. StressClient Instances (multiple)
• Listener Loop coroutine
• Sender coroutine
• Two asyncio.Event objects for synchronization (cards_populated, clear_to_send)
d. External WebSocket Server
• Accepts client connections
• Sends messages (welcome, ping, startingCards, turn, etc.)
• Receives responses (options request, pong, moves)
e. CI Pipeline & Tests (optional)
• Runs unit tests against src/ modules
• Ensures code quality on push (ci.yml)
Relationships and Data Flows
• Config Loader → Orchestrator (injects settings)
• Orchestrator → spawns StressClient instances
• Listener Loop ← server messages
• Sender → server actions
• Within each StressClient:
• Listener Loop sets events on receiving startingCards / turn
• Sender waits on events, then sends move
Architectural Patterns & Design Principles
• Asynchronous concurrency via asyncio.TaskGroup
• Separation of concerns:
• config.py for environment loading
• client.py for protocol logic
• main.py for orchestration
• Event-driven synchronization (asyncio.Events)