WebSocket Test Harness

WebSocket Test Harness

A standalone Go application for testing the TMI WebSocket interface for collaborative threat modeling.

Source Location: wstest/ directory in the TMI repository

Features

• OAuth authentication with TMI test provider using login hints (uses idp=test)
• Host mode: Creates threat models, adds participants, creates diagrams, and starts collaboration sessions
• Participant mode: Polls for available collaboration sessions and joins them
• Comprehensive logging of all network interactions and WebSocket messages
• Supports multiple concurrent instances
• Uses the Gorilla WebSocket library

Building

Use the make target (preferred):

make build-wstest

Or build directly:

cd wstest
go mod tidy
go build -o wstest

Usage

Host Mode

Start as a host to create a new collaboration session:

# Basic host mode
./wstest --user alice --host

# Host mode with participants
./wstest --user alice --host --participants "bob,charlie,dave"

# Custom server
./wstest --server http://localhost:8080 --user alice --host

Participant Mode

Start as a participant to join existing collaboration sessions:

# Join any available session
./wstest --user bob

# Multiple participants
./wstest --user charlie &
./wstest --user dave &

Command Line Options

Option	Description	Default
--server <url>	Server URL	localhost:8080
--user <hint>	User login hint	Required
--host	Run in host mode	false
--participants <list>	Comma-separated list of participant hints (host mode only)	Empty

Test Scenarios

Basic Two-User Test

Terminal 1 (Host):

./wstest --user alice --host --participants "bob"

Terminal 2 (Participant):

./wstest --user bob

Multi-User Collaboration

Terminal 1 (Host):

./wstest --user alice --host --participants "bob,charlie,dave"

Terminals 2-4 (Participants):

./wstest --user bob
./wstest --user charlie
./wstest --user dave

Automated Multi-Terminal Test

Use the make target to automatically launch three terminal windows:

make wstest

This launches:

• Alice as host with participants "bob,charlie,hobobarbarian@gmail.com"
• Bob as participant
• Charlie as participant

Each instance has a 30-second timeout to prevent runaway processes.

Expected WebSocket Messages

Upon joining a collaboration session, clients receive:

participants_update

Full list of current participants (includes presenter info if any).

Structure:

{
  "message_type": "participants_update",
  "initiating_user": { /* user who triggered the update, or null */ },
  "participants": [
    {
      "user": {
        "principal_type": "user",
        "provider": "tmi",
        "provider_id": "alice@tmi.local",
        "email": "alice@tmi.local",
        "display_name": "Alice (TMI User)"
      },
      "permissions": "owner",
      "last_activity": "2025-01-24T12:00:00Z"
    }
  ],
  "host": { /* host user object */ },
  "current_presenter": { /* presenter user object, or null */ }
}

All subsequent WebSocket messages (sent and received) are logged with timestamps and pretty-printed JSON formatting.

OAuth Flow

The harness implements the OAuth authorization code flow:

1. Starts a local HTTP server on a random port for the callback
2. Makes a GET request to /oauth2/authorize?idp=test&login_hint=<user>&client_callback=<url>&scope=openid+email+profile
3. Follows the redirect to the local callback server
4. Exchanges the authorization code for tokens via POST to /oauth2/token
5. Uses the access token for all subsequent API calls and WebSocket connection

Note: The harness uses idp=test which is the TMI development OAuth provider that creates test users based on login hints.

Logging

All network interactions are logged to console:

• HTTP requests show method, URL, and request bodies
• HTTP responses show status codes and response bodies
• WebSocket messages are timestamped and pretty-printed
• OAuth callback parameters are logged in detail

Exit

Use Ctrl+C to gracefully shutdown the application. The WebSocket connection will be properly closed.

Make Targets

Target	Description
make build-wstest	Build the WebSocket test harness binary
make wstest	Launch 3-terminal test (alice as host, bob & charlie as participants)
make monitor-wstest	Run WebSocket harness with user 'monitor' in foreground
make clean-wstest	Stop all running WebSocket test harness instances

Troubleshooting

Connection Fails Immediately

Check:

1. Server is running (make start-dev)
2. Correct server URL (default is localhost:8080)
3. OAuth flow completes successfully (check console output)

No Sessions Found (Participant Mode)

Check:

1. Host has started a session first
2. Participant user has been added to the threat model authorization
3. Session is still active (not timed out)

WebSocket Disconnects

Check:

1. Server logs for errors
2. Session hasn't been terminated by host
3. Network connectivity

Related Documentation

• WebSocket-API-Reference - Full WebSocket API documentation
• Collaborative-Threat-Modeling - Collaboration features overview
• Debugging-Guide - General debugging procedures
• AsyncAPI Specification - WebSocket message schemas