WebSocket Playground

Chanx includes a powerful WebSocket playground that provides a visual interface for exploring and testing WebSocket endpoints. This tool makes it easier to develop, debug, and document your WebSocket APIs.

Features

The WebSocket playground offers several key features:

Endpoint Discovery: Automatically discovers all available WebSocket endpoints
Interactive Connection: Connect to endpoints with customizable parameters
Message Composer: Create and send structured JSON messages
Message History: View all sent and received messages with syntax highlighting
Authentication Testing: Test endpoints with different authentication methods
Example Messages: Generate example messages based on your schema definitions

Enabling the Playground

To enable the WebSocket playground in your project:

Add the playground URLs to your project’s URL configuration:

# urls.py
from django.urls import path, include

urlpatterns = [
    # ...
    path('chanx/', include('chanx.playground.urls')),
    # ...
]

Ensure the playground templates and static files are accessible:

# settings.py
INSTALLED_APPS = [
    # ...
    'chanx',
    # ...
]

Access the playground at /chanx/playground/websocket/ in your browser

Using the Playground

The playground interface is divided into several sections:

Endpoint Selection

The left panel displays all discovered WebSocket endpoints with their URLs and descriptions. Endpoints are automatically discovered from your URL routing configuration.

# routing.py example that will be discovered
from django.urls import re_path
from myapp.consumers import ChatConsumer, NotificationConsumer

websocket_urlpatterns = [
    re_path(r'ws/chat/(?P<room_id>\w+)/$', ChatConsumer.as_asgi()),
    re_path(r'ws/notifications/$', NotificationConsumer.as_asgi()),
]

Connection Panel

The connection panel allows you to:

View the complete WebSocket URL
Manage path parameters for endpoints with URL parameters
Add authentication headers or query parameters
Connect and disconnect from the WebSocket

For endpoints with URL parameters (like room_id in the example above), you’ll be able to enter parameter values before connecting.

Message Composer

The message composer provides:

A JSON editor with syntax highlighting
Example message templates based on your consumer’s message schema
A “Send” button to transmit the message

Example messages are automatically generated from your INCOMING_MESSAGE_SCHEMA class, helping you send correctly structured messages.

Message History

The message history panel shows:

All sent and received messages in chronological order
Message direction (sent/received)
Formatted JSON with syntax highlighting
Timestamps for each message

Authentication Testing

The playground supports testing authenticated endpoints through:

Cookie-based authentication (using your browser’s cookies)
Header-based authentication (by adding custom headers)
Query parameter authentication

For example, to test a token-authenticated endpoint:

In the headers section, add: Authorization: Token your_token_here
Or in the URL parameters section, add: token=your_token_here

Generating Example Messages

The playground automatically generates example messages based on your message schema:

from typing import Literal, Optional
from chanx.messages.base import BaseIncomingMessage, BaseMessage


class ChatMessage(BaseMessage):
    """Send a chat message to the room."""
    action: Literal["chat"] = "chat"
    payload: str


class TypingMessage(BaseMessage):
    """Indicate user is typing."""
    action: Literal["typing"] = "typing"
    payload: Optional[bool] = True


class MyChatMessages(BaseIncomingMessage):
    """Chat application messages."""
    message: ChatMessage | TypingMessage

For the consumer using this schema:

class ChatConsumer(AsyncJsonWebsocketConsumer):
    INCOMING_MESSAGE_SCHEMA = MyChatMessages

The playground will generate these example messages:

// ChatMessage example
{
    "action": "chat",
    "payload": "Sample message text"
}

// TypingMessage example
{
    "action": "typing",
    "payload": true
}

These examples help you understand the expected message format and quickly test your endpoints.

Security Considerations

The WebSocket playground should be used cautiously in production environments:

Disable in Production: Consider disabling the playground in production
Restrict Access: If enabled in production, use authentication to restrict access
CORS Settings: Be aware of your CORS settings when using the playground
Sensitive Data: Avoid sending sensitive data through the playground

To disable the playground in production:

# urls.py
from django.urls import path, include
from django.conf import settings

urlpatterns = [
    # ...
]

if settings.DEBUG:
    # Only add playground URLs in development
    urlpatterns += [
        path('chanx/', include('chanx.playground.urls')),
    ]

Or restrict access with a decorator:

# Custom playground URLs
from django.urls import path
from django.contrib.admin.views.decorators import staff_member_required
from chanx.playground.views import WebSocketPlaygroundView, WebSocketInfoView

urlpatterns = [
    path(
        'admin/websocket/',
        staff_member_required(WebSocketPlaygroundView.as_view()),
        name='websocket_playground'
    ),
    path(
        'admin/websocket-info/',
        staff_member_required(WebSocketInfoView.as_view()),
        name='websocket_info'
    ),
]

Customizing the Playground

You can customize the playground by:

Override Templates: Create your own version of the playground template
Extend Views: Subclass the playground views to add custom behavior
Custom Styling: Add your own CSS to modify the appearance

To override the template:

Create a file at templates/playground/websocket.html in your project
Copy the original template content from the package
Modify as needed

Advanced Usage

Testing Different Authentication Methods

The playground allows you to test different authentication methods:

Session Authentication: Works automatically with your browser’s cookies
Token Authentication: Add an Authorization header
Basic Authentication: Add a Basic Authentication header
Custom Authentication: Add any required headers or parameters

Working with Binary Messages

While the playground is designed for JSON messages, you can also work with binary data:

Use the “Send Binary” option if available
Or encode binary data in a compatible format (Base64)

Multiple Connections

You can open multiple playground tabs to test:

Group messaging between different clients
User-to-user messaging
Broadcast functionality