mockrtc 0.1.0

package/test/integration/smoke-test.spec.ts

@@ -0,0 +1,100 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    MockRTC,
+    expect,
+    delay
+} from '../test-setup';
+
+describe("MockRTC smoke test:", function () {
+
+    const mockRTC = MockRTC.getRemote({ recordMessages: true });
+
+    beforeEach(() => mockRTC.start());
+    afterEach(() => mockRTC.stop());
+
+    it("should pass the README example test", async () => {
+        // Create a mock peer who sends 'Goodbye' after receiving its first message.
+        const mockPeer = await mockRTC
+            .buildPeer()
+            .waitForNextMessage()
+            .thenSend('Goodbye');
+
+        // Create a data connection:
+        const localConnection = new RTCPeerConnection();
+        const dataChannel = localConnection.createDataChannel("dataChannel");
+
+        const localOffer = await localConnection.createOffer();
+        await localConnection.setLocalDescription(localOffer);
+
+        // Get the remote details for the mock peer:
+        const { answer } = await mockPeer.answerOffer(localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        // Once the connection is open, message the peer
+        dataChannel.onopen = () => {
+            dataChannel.send('Hello');
+        };
+
+        // Wait for a response:
+        const message = await new Promise((resolve) => {
+            dataChannel.addEventListener('message', (event) => resolve(event.data));
+        });
+        expect(message).to.equal('Goodbye'); // <-- We get our mock response!
+
+        // Assert on the messages the mock peer received:
+        expect(await mockPeer.getAllMessages()).to.deep.equal(['Hello']);
+    });
+
+    it("should pass the README proxy example", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForNextMessage() // Wait for and drop the first datachannel message
+            .send('MockRTC injected message') // Send a message on every data channel
+            .thenPassThrough(); // Then proxy everything else
+
+        const localConn = new RTCPeerConnection();
+
+        // The magic:
+        MockRTC.hookWebRTCConnection(localConn, mockPeer);
+        // ^ This redirects all connA's traffic via the mock peer, no matter who it connects to.
+
+        // Normal WebRTC setup using real browser connections:
+        const localOffer = await localConn.createOffer();
+        const localDataChannel = localConn.createDataChannel("dataChannel");
+        localConn.setLocalDescription(localOffer);
+
+        const remoteConn = new RTCPeerConnection();
+        remoteConn.setRemoteDescription(localOffer);
+        const remoteAnswer = await remoteConn.createAnswer();
+        remoteConn.setLocalDescription(remoteAnswer);
+        localConn.setRemoteDescription(remoteAnswer);
+
+        const log: string[] = [];
+
+        localDataChannel.onopen = () => {
+            localDataChannel.addEventListener('message', ({ data }) => log.push(`LOCAL: ${data}`));
+            localDataChannel.send('local message 1');
+            localDataChannel.send('local message 2');
+        };
+
+        remoteConn.addEventListener('datachannel', async ({ channel }) => {
+            channel.addEventListener('message', ({ data }) => log.push(`REMOTE: ${data}`));
+            await delay(10); // Delay to guarantee ordering - skipped in README but that's OK
+            channel.send("remote message 1");
+            channel.send("remote message 2");
+        });
+
+        await delay(200);
+
+        expect(log).to.deep.equal([
+            'LOCAL: MockRTC injected message',
+            'REMOTE: local message 2',
+            'LOCAL: remote message 1',
+            'LOCAL: remote message 2'
+        ]);
+    });
+
+});

package/test/integration/wait-steps.spec.ts

@@ -0,0 +1,225 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    MockRTC,
+    expect,
+    waitForState,
+    delay,
+    waitForChannelOpen
+} from '../test-setup';
+
+describe("Wait steps", function () {
+
+    const mockRTC = MockRTC.getRemote();
+
+    beforeEach(() => mockRTC.start());
+    afterEach(() => mockRTC.stop());
+
+    it("should be able to wait for a duration before a step", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .sleep(400)
+            .thenSend('delayed message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const receivedMessages: string[] = [];
+        const testChannel = localConnection.createDataChannel('data-channel');
+        testChannel.addEventListener('message', ({ data }) => { receivedMessages.push(data) });
+
+        const localOffer = await localConnection.createOffer();
+        await localConnection.setLocalDescription(localOffer);
+        const { answer } = await mockPeer.answerOffer(localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        await waitForState(localConnection, 'connected');
+
+        await delay(200);
+        expect(receivedMessages).to.deep.equal([]);
+
+        await delay(300);
+        expect(receivedMessages).to.deep.equal(['delayed message']);
+    });
+
+    it("should be able to wait the existence of a channel", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForChannel()
+            .thenSend('delayed message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const { offer, setAnswer } = await mockPeer.createOffer();
+        await localConnection.setRemoteDescription(offer);
+        const localAnswer = await localConnection.createAnswer();
+        await localConnection.setLocalDescription(localAnswer);
+        await setAnswer(localAnswer);
+
+        await waitForState(localConnection, 'connected');
+        await delay(100);
+
+        const receivedMessages: string[] = [];
+        const testChannel = localConnection.createDataChannel('data-channel');
+        testChannel.addEventListener('message', ({ data }) => { receivedMessages.push(data) });
+
+        await delay(100);
+        expect(receivedMessages).to.deep.equal(['delayed message']);
+    });
+
+    it("should be able to wait for the existence of a specific named channel", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForChannel('message-channel')
+            .thenSend('delayed message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const { offer, setAnswer } = await mockPeer.createOffer();
+        await localConnection.setRemoteDescription(offer);
+        const localAnswer = await localConnection.createAnswer();
+        await localConnection.setLocalDescription(localAnswer);
+        await setAnswer(localAnswer);
+
+        await waitForState(localConnection, 'connected');
+        await delay(100);
+
+        const receivedIgnoredChannelMessages: string[] = [];
+        const ignoredChannel = localConnection.createDataChannel('ignored-channel');
+        ignoredChannel.addEventListener('message', ({ data }) => { receivedIgnoredChannelMessages.push(data) });
+
+        await delay(100);
+        expect(receivedIgnoredChannelMessages).to.deep.equal([]);
+
+        const receivedRealChannelMessages: string[] = [];
+        const testChannel = localConnection.createDataChannel('message-channel');
+        testChannel.addEventListener('message', ({ data }) => { receivedRealChannelMessages.push(data) });
+
+        await delay(100);
+        expect(receivedRealChannelMessages).to.deep.equal(['delayed message']);
+    });
+
+    it("should be able to wait for the addition of a media track", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForTrack()
+            .thenSend('after-track message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const receivedMessages: string[] = [];
+        localConnection.createDataChannel('message-channel')
+            .addEventListener('message', ({ data }) => { receivedMessages.push(data) });
+
+        const localOffer = await localConnection.createOffer();
+        await localConnection.setLocalDescription(localOffer);
+        const { answer, session } = await mockPeer.answerOffer(await localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        await waitForState(localConnection, 'connected');
+        await delay(100);
+        expect(receivedMessages).to.deep.equal([]);
+
+        // Add (listen only) media tracks and renegotiate:
+        const updatedOffer = await localConnection.createOffer({
+            offerToReceiveAudio: true,
+            offerToReceiveVideo: true
+        });
+        localConnection.setLocalDescription(updatedOffer);
+        const updatedAnswer = await session.answerOffer(updatedOffer);
+        await localConnection.setRemoteDescription(updatedAnswer);
+
+        await delay(100);
+        expect(receivedMessages).to.deep.equal(['after-track message']);
+    });
+
+    it("should be able to wait for media data", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForNextMedia()
+            .thenSend('after-track message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const receivedMessages: string[] = [];
+        localConnection.createDataChannel('message-channel')
+            .addEventListener('message', ({ data }) => { receivedMessages.push(data) });
+
+        const localOffer = await localConnection.createOffer({
+            offerToReceiveAudio: true,
+            offerToReceiveVideo: true
+        });
+        await localConnection.setLocalDescription(localOffer);
+        const { answer, session } = await mockPeer.answerOffer(await localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        await waitForState(localConnection, 'connected');
+        await delay(100);
+        expect(receivedMessages).to.deep.equal([]);
+
+        // Add media tracks and renegotiate:
+        const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
+        stream.getTracks().forEach((track) => localConnection.addTrack(track, stream));
+
+        const updatedOffer = await localConnection.createOffer();
+        localConnection.setLocalDescription(updatedOffer);
+        const updatedAnswer = await session.answerOffer(updatedOffer);
+        await localConnection.setRemoteDescription(updatedAnswer);
+
+        await delay(1000);
+        expect(receivedMessages).to.deep.equal(['after-track message']);
+    });
+
+    it("should be able to wait for a message on any channel", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForNextMessage()
+            .thenSend('delayed message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const receivedMessages: string[] = [];
+        const testChannel = localConnection.createDataChannel('data-channel');
+        testChannel.addEventListener('message', ({ data }) => { receivedMessages.push(data) });
+
+        const localOffer = await localConnection.createOffer();
+        await localConnection.setLocalDescription(localOffer);
+        const { answer } = await mockPeer.answerOffer(localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        await waitForState(localConnection, 'connected');
+
+        await delay(100);
+        expect(receivedMessages).to.deep.equal([]);
+
+        testChannel.send('test message');
+        await delay(100);
+        expect(receivedMessages).to.deep.equal(['delayed message']);
+    });
+
+    it("should be able to wait for a message on a specific named channel", async () => {
+        const mockPeer = await mockRTC.buildPeer()
+            .waitForNextMessageOnChannel("message-channel")
+            .thenSend('delayed message');
+
+        const localConnection = new RTCPeerConnection();
+
+        const receivedMessages: string[] = [];
+        const ignoredChannel = localConnection.createDataChannel('ignored-channel');
+        const messageChannel = localConnection.createDataChannel('message-channel');
+        messageChannel.addEventListener('message', ({ data }) => { receivedMessages.push(data) });
+
+        const localOffer = await localConnection.createOffer();
+        await localConnection.setLocalDescription(localOffer);
+        const { answer } = await mockPeer.answerOffer(localOffer);
+        await localConnection.setRemoteDescription(answer);
+
+        await waitForState(localConnection, 'connected');
+
+        await waitForChannelOpen(ignoredChannel);
+        ignoredChannel.send('test message');
+        await delay(100);
+        expect(receivedMessages).to.deep.equal([]);
+
+        messageChannel.send('test message');
+        await delay(100);
+        expect(receivedMessages).to.deep.equal(['delayed message']);
+    });
+
+});

package/test/start-test-admin-server.ts

@@ -0,0 +1,12 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const mockrtc = require('../src/main');
+mockrtc.getAdminServer().start().then(() => {
+    console.log("Test admin server started");
+}).catch((error: any) => {
+    console.error(error);
+    process.exit(1);
+});

package/test/test-setup.ts

@@ -0,0 +1,136 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { expect } from "chai";
+
+import * as MockRTC from "../src/main-browser";
+
+export { MockRTC };
+
+// When running continuous tests, where the admin server restarts, we have a race condition
+// between server restart & test run. To fix that, here we wait 10s for the admin server to
+// become accessible before we run any tests.
+before(async function () {
+    this.timeout(10000);
+    let shownMessage = false;
+
+    while (true) {
+        try {
+            const server = MockRTC.getRemote();
+            await server.start();
+            await server.stop();
+            break;
+        } catch (e: any) {
+            if (!shownMessage) {
+                shownMessage = true;
+                if (!(e instanceof TypeError)) {
+                    console.log("Could not connect to admin server");
+                    throw e;
+                } else {
+                    console.log("Waiting for admin server to start...");
+                }
+            }
+        }
+    }
+});
+
+export async function waitForState(connection: RTCPeerConnection, state: RTCPeerConnectionState) {
+    await new Promise<void>((resolve) => {
+        if (connection.connectionState === state) resolve();
+        else {
+            connection.addEventListener('connectionstatechange', () => {
+                if (connection.connectionState === state) resolve();
+            });
+        }
+    });
+}
+
+export async function waitForChannelOpen(channel: RTCDataChannel) {
+    await new Promise<void>((resolve) => {
+        if (channel.readyState === 'open') resolve();
+        else {
+            channel.addEventListener('open', () => resolve());
+        }
+    });
+}
+
+export async function waitForChannelClose(channel: RTCDataChannel) {
+    await new Promise<void>((resolve) => {
+        if (channel.readyState === 'closed') resolve();
+        else {
+            channel.addEventListener('close', () => resolve());
+        }
+    });
+}
+
+export function delay(durationMs: number) {
+    return new Promise<void>((resolve) => {
+        setTimeout(resolve, durationMs);
+    });
+}
+
+// Connect a peer & signalling channel to connect with no specific direction specified, using
+// the official example code from the spec:
+export function setupPerfectNegotiation(
+    peer: RTCPeerConnection,
+    polite: boolean,
+    signaler: { send: (msg: any) => void, onmessage: (msg: any) => void }
+) {
+    // Example almost verbatim from https://w3c.github.io/webrtc-pc/#perfect-negotiation-example
+
+    // keep track of some negotiation state to prevent races and errors
+    let makingOffer = false;
+    let ignoreOffer = false;
+    let isSettingRemoteAnswerPending = false;
+
+    // send any ice candidates to the other peer
+    peer.onicecandidate = ({candidate}) => signaler.send({candidate});
+
+    // let the "negotiationneeded" event trigger offer generation
+    peer.onnegotiationneeded = async () => {
+        try {
+            makingOffer = true;
+            await peer.setLocalDescription();
+            signaler.send({description: peer.localDescription});
+        } catch (err) {
+            console.error('onnegotiationneeded', err);
+        } finally {
+            makingOffer = false;
+        }
+    };
+
+    signaler.onmessage = async ({description, candidate}) => {
+        try {
+            if (description) {
+                // An offer may come in while we are busy processing SRD(answer).
+                // In this case, we will be in "stable" by the time the offer is processed
+                // so it is safe to chain it on our Operations Chain now.
+                const readyForOffer = !makingOffer &&
+                    (peer.signalingState == "stable" || isSettingRemoteAnswerPending);
+                const offerCollision = description.type == "offer" && !readyForOffer;
+
+                ignoreOffer = !polite && offerCollision;
+                if (ignoreOffer) {
+                    return;
+                }
+                isSettingRemoteAnswerPending = description.type == "answer";
+                await peer.setRemoteDescription(description); // SRD rolls back as needed
+                isSettingRemoteAnswerPending = false;
+                if (description.type == "offer") {
+                    await peer.setLocalDescription();
+                    signaler.send({description: peer.localDescription});
+                }
+            } else if (candidate) {
+                try {
+                    await peer.addIceCandidate(candidate);
+                } catch (err) {
+                    if (!ignoreOffer) throw err; // Suppress ignored offer's candidates
+                }
+            }
+        } catch (err) {
+            console.error('onmessage error', err);
+        }
+    }
+}

package/test/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "compilerOptions": {
+        "target": "es6",
+        "module": "commonjs",
+        "strict": true
+    },
+    "include": [
+        "../custom-typings/*.d.ts",
+        "**/*.ts",
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+        "target": "es6",
+        "module": "commonjs",
+        "outDir": "./dist",
+        "declaration": true,
+        "sourceMap": true,
+        "strict": true
+    },
+    "include": [
+        "custom-typings/*.d.ts",
+        "src/**/*.ts"
+    ]
+}

package/typedoc.json

@@ -0,0 +1,19 @@
+{
+    "name": "MockRTC API Reference",
+    "categorizeByGroup": false,
+    "categoryOrder": [
+        "API",
+        "Steps",
+        "Final Steps",
+        "*"
+    ],
+    "readme": "none",
+    "validation": {
+        "invalidLink": true
+    },
+    "treatWarningsAsErrors": true,
+    "excludePrivate": true,
+    "excludeProtected": true,
+    "excludeInternal": true,
+    "out": "typedoc/"
+}

package/wallaby.js

@@ -0,0 +1,41 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Tim Perry <tim@httptoolkit.tech>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+module.exports = (wallaby) => {
+  return {
+    files: [
+      'package.json',
+      'src/**/*.ts',
+      'test/**/*.ts',
+      '!test/**/*.spec.ts'
+    ],
+    tests: [
+      'test/**/*.spec.ts'
+    ],
+
+    preprocessors: {
+      // Package.json points `main` to the built output. We use this a lot in the integration tests, but we
+      // want wallaby to run on raw source. This is a simple remap of paths to lets us do that.
+      'test/integration/**/*.ts': file => {
+        return file.content.replace(
+          /("|')..((\/..)+)("|')/g,
+          '"..$2/src/main"'
+        );
+      }
+    },
+
+    workers: {
+      initial: 1,
+      regular: 1,
+      restart: true
+    },
+
+    testFramework: 'mocha',
+    env: {
+      type: 'node'
+    },
+    debug: true
+  };
+};