MoQ Interop Runner

July 22, 2026 · View on GitHub

A framework for testing interoperability between MoQT (Media over QUIC Transport) implementations.

Why Interoperability Testing?

The IETF standards process requires "multiple, independent, and interoperable implementations" before a specification can advance (RFC 2026). Interop testing catches ambiguities in specs that only surface when different teams interpret the same text differently, and builds confidence that implementations will work together in real deployments.

This project is modeled on the QUIC Interop Runner, which was instrumental during QUIC standardization.

Non-Goals

Reference compliance testing. This project tests whether different MoQT implementations can successfully communicate with each other - interoperability, not compliance. We're not building a reference implementation that serves as the definitive arbiter of spec compliance. Interop testing happens between implementations - if two implementations agree and work together, that's what we care about.

Adversarial/negative testing. Our test cases follow scenarios that occur between valid MoQT implementations. We don't require test clients to produce malformed messages or violate the protocol to test error handling. That kind of negative testing requires purpose-built tools capable of representing illegal protocol states - not something we expect from production MoQT implementations.

Browser-based implementations (for now). The current Docker-based flow assumes CLI execution. Non-browser TypeScript/Bun clients work via WebTransport polyfills (e.g. moq-dev-js), but browser-only implementations can't plug in directly today.

Getting Started

Start with Getting Started for a guided walkthrough; run make help to discover commands.

Prerequisites

  • Docker with buildx support (for building multi-platform images)
  • jq (for parsing JSON configuration)
  • openssl (for generating TLS certificates)
  • bash (works with macOS default bash 3.2+)

Overview

This project provides:

  • Implementation Registry (implementations.json) - A catalog of MoQT implementations with their capabilities, Docker images, and public relay endpoints
  • Test Orchestration - Scripts to run interop tests across implementation combinations
  • Test Specifications (docs/TEST-SPECIFICATIONS.md) - Standardized test cases that any implementation can implement

Quick Start

# List registered implementations and their endpoints
make interop-list

# Build the moq-rs test client (one-time, takes a few minutes)
make build-moq-rs BUILD_ARGS="--target client"

# Run tests against all public relays
make interop-remote

Filter a single relay: make interop-remote RELAY=moxygen. See Getting Started for more, or make help for all commands.

Registered Implementations

ImplementationOrganizationDraft VersionsRolesPublic Endpoints
moq-rsCloudflare14relay, clienthttps://draft-14.cloudflare.mediaoverquic.com:443/moq
moq-rs (draft-16)Cloudflare16relay, client
moxygenMeta14, 16relay, clienthttps://fb.mvfst.net:9448/moq-relay
moq (moq-dev)Luke Curley14-17relay, clienthttps://cdn.moq.dev/anon
moq (moq-dev, JS)Luke Curley14-17client
quiche-moqGoogle16relayhttps://quichemoq.dev:443
moqtransportTUM13relay(no persistent relay)
MOQtailOzU16relayhttps://relay.moqtail.dev
libquicrCisco14relayhttps://us-west-2.relay.quicr.org:33437/relay
imquicMeetecho16-18relay, clienthttps://lminiero.it:9000
moq-goVsevolod Strukchinsky18relay, client
moqtopusKota Yatagai18client
xquicAlibaba14, 18relay, client

This table is a snapshot — run make interop-list or see implementations.json for the current state. See IMPLEMENTATIONS.md for how to add your implementation.

Test Cases

Tests are organized by functional category:

TestCategoryDescription
setup-onlySessionConnect, complete SETUP exchange, close gracefully
announce-onlyNamespaceAnnounce namespace, receive OK, close
publish-namespace-doneNamespaceAnnounce, then send PUBLISH_NAMESPACE_DONE
subscribe-errorSubscriptionSubscribe to non-existent track, expect error
announce-subscribeSubscriptionPublisher announces, subscriber subscribes
subscribe-before-announceSubscriptionSubscribe before publisher announces

See docs/tests/TEST-CASES.md for detailed specifications with protocol references.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Test Orchestrator                          │
│  (run-interop-tests.sh / Makefile)                              │
│  - Reads implementations.json                                    │
│  - Manages Docker containers or tests remote endpoints           │
│  - Collects results                                              │
└─────────────────────────────────────────────────────────────────┘
         │                                    │
         ▼                                    ▼
┌─────────────────────┐            ┌─────────────────────┐
│   Test Client       │            │   Relay Under Test  │
│   (Docker image)    │───────────▶│   (Docker or remote)│
│                     │   MoQT     │                     │
│   Runs test cases,  │            │   Implementation    │
│   reports results   │            │   being tested      │
└─────────────────────┘            └─────────────────────┘

Key Files

PathPurpose
implementations.jsonImplementation registry (the central config file)
run-interop-tests.shMain test orchestration script
MakefileAll commands — run make help to see them
docs/Getting started, test specs, interface docs
adapters/Thin Docker wrappers for implementations (README)
builds/Source-based Docker builds (README)

MoQT Implementations

Inspiration

Contributing

Contributions welcome! Key areas:

  1. Add your implementation - See IMPLEMENTATIONS.md
  2. Propose new test cases - Open an issue or PR to docs/tests/TEST-CASES.md
  3. Build a test client - See docs/IMPLEMENTING-A-TEST-CLIENT.md
  4. Improve tooling - Better reporting, CI integration, etc.

Acknowledgments

The initial implementation of this framework was generously supported by Cloudflare.

License

Licensed under either of:

at your option.