in-app-notification-test-author

Overview

In-app notifications are the channel that email, SMS, push, and webhook tests do not cover: real-time messages delivered to a connected client inside the application, typically via a persistent transport. Four transport stacks are common:

The skill walks a common test workflow and then provides per-transport patterns. Transport-level protocol tests (frame parsing, flow control, SSE reconnect timing) belong to qa-realtime-protocols; this skill tests the notification feature layer that runs on top.

When to use

• The product has a notification center, activity feed, or live-update panel inside the app UI.
• Tests need to verify that a server-side event (new message, payment received, status change) reaches the connected client and updates UI state.
• A regression suite must cover unread/read state transitions and fan-out to multiple concurrent sessions.
• Tests must cover offline queuing and in-order delivery after reconnect.

Step 1 - Choose the isolation level

Default: mock the transport for unit tests of the notification handler; use the Firebase emulator for RTDB / Firestore delivery tests; reserve full integration for fan-out and ordering scenarios.

Step 2 - WebSocket delivery tests

Per RFC 6455 Section 4, the opening handshake upgrades HTTP to a persistent bidirectional channel (101 Switching Protocols). The server sends a notification as a text or binary frame (opcodes 0x1 / 0x2 per RFC 6455 Section 5.2). Tests mock at the frame-receive boundary so the notification handler is exercised without a live server.

Test pattern (Node.js / Jest with ws):

const WebSocket = require('ws');
const { jest } = require('@jest/globals');

describe('in-app notification handler - WebSocket', () => {
  let server;
  let wss;

  beforeEach((done) => {
    wss = new WebSocket.Server({ port: 0 }, done);
  });

  afterEach((done) => {
    wss.close(done);
  });

  it('delivers notification payload to the client handler', (done) => {
    wss.once('connection', (ws) => {
      ws.send(JSON.stringify({ type: 'NEW_MESSAGE', id: 'n-1', body: 'Hello' }));
    });

    const client = new WebSocket(`ws://localhost:${wss.options.port}`);
    client.on('message', (data) => {
      const msg = JSON.parse(data);
      expect(msg.type).toBe('NEW_MESSAGE');
      expect(msg.id).toBe('n-1');
      client.close();
      done();
    });
  });

  it('marks notification unread on receipt', (done) => {
    wss.once('connection', (ws) => {
      ws.send(JSON.stringify({ type: 'NEW_MESSAGE', id: 'n-2', body: 'Hi' }));
    });

    const client = new WebSocket(`ws://localhost:${wss.options.port}`);
    const notificationStore = createNotificationStore(); // app module under test

    client.on('message', (data) => {
      notificationStore.receive(JSON.parse(data));
      expect(notificationStore.unreadCount()).toBe(1);
      client.close();
      done();
    });
  });
});

Per RFC 6455 Section 7.4.1, the close code 1000 signals normal closure; 1001 means the endpoint is going away. Tests for reconnect logic should simulate 1001 or 1006 (abnormal closure) and assert that the client attempts reconnection and re-subscribes to notification channels.

Step 3 - SSE delivery tests

Per the WHATWG Server-Sent Events spec, EventSource dispatches events as MessageEvent objects carrying data and lastEventId, and on disconnect the user agent auto-reconnects with a Last-Event-ID header so the server resumes from the last acknowledged event. Tests should assert this recovery path.

Test pattern (Node.js with eventsource + express):

const EventSource = require('eventsource');
const express = require('express');

describe('in-app notification handler - SSE', () => {
  let app;
  let httpServer;
  let sentEvents = [];

  beforeAll((done) => {
    app = express();
    app.get('/notifications/stream', (req, res) => {
      res.set({ 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
      sentEvents.forEach(({ id, data }) => {
        res.write(`id: ${id}\ndata: ${JSON.stringify(data)}\n\n`);
      });
    });
    httpServer = app.listen(0, done);
  });

  afterAll((done) => httpServer.close(done));

  it('dispatches notification event to the handler', (done) => {
    sentEvents = [{ id: 'e-1', data: { type: 'PAYMENT_RECEIVED', amount: 50 } }];
    const port = httpServer.address().port;
    const es = new EventSource(`http://localhost:${port}/notifications/stream`);

    es.onmessage = (event) => {
      const payload = JSON.parse(event.data);
      expect(payload.type).toBe('PAYMENT_RECEIVED');
      expect(event.lastEventId).toBe('e-1');
      es.close();
      done();
    };
  });
});

An SSE event's retry field (milliseconds) sets the client reconnection delay; assert the client honors a server-supplied value in integration tests.

Step 4 - Firebase Realtime Database listener tests

onValue() fires once immediately with current data and again on every change at that location and below (RTDB read/write docs). Run listener tests against the Firebase Local Emulator Suite, not production. Emulator setup plus the write and read-state test patterns are in references/firebase-listener-tests.md.

Step 5 - Firestore onSnapshot tests

onSnapshot() fires immediately with the current document and again on each change, carrying metadata.hasPendingWrites and metadata.fromCache; assert fromCache transitions for offline-then-reconnect delivery (Firestore listen docs). The includeMetadataChanges test pattern is in references/firebase-listener-tests.md.

Step 6 - Notification center read/unread state

In-app notification centers track aggregate unread counts and per-notification read state. Test the state machine independently of the transport:

describe('notification store', () => {
  it('increments unread count when a new notification arrives', () => {
    const store = createNotificationStore();
    store.receive({ id: 'n-1', type: 'COMMENT', read: false });
    expect(store.unreadCount()).toBe(1);
  });

  it('decrements unread count when notification is marked read', () => {
    const store = createNotificationStore();
    store.receive({ id: 'n-1', type: 'COMMENT', read: false });
    store.markRead('n-1');
    expect(store.unreadCount()).toBe(0);
  });

  it('markAllRead resets unread count to zero', () => {
    const store = createNotificationStore();
    ['n-1', 'n-2', 'n-3'].forEach((id) =>
      store.receive({ id, type: 'COMMENT', read: false })
    );
    store.markAllRead();
    expect(store.unreadCount()).toBe(0);
  });
});

Step 7 - Fan-out to multiple sessions

Fan-out (one server event reaching N simultaneously connected clients) is a distinct failure mode from single-client delivery. Test with multiple concurrent WebSocket or SSE clients:

it('delivers the same notification to all connected sessions', (done) => {
  const PORT = wss.options.port;
  const received = [];
  const SESSIONS = 3;

  const clients = Array.from({ length: SESSIONS }, () => new WebSocket(`ws://localhost:${PORT}`));

  clients.forEach((ws) => {
    ws.on('message', (data) => {
      received.push(JSON.parse(data));
      if (received.length === SESSIONS) {
        const ids = received.map((m) => m.id);
        expect(new Set(ids).size).toBe(1);         // same notification id
        expect(ids.length).toBe(SESSIONS);         // all sessions received it
        clients.forEach((c) => c.close());
        done();
      }
    });
  });

  // wait for all clients to connect, then broadcast
  let connected = 0;
  wss.on('connection', () => {
    connected += 1;
    if (connected === SESSIONS) broadcastNotification({ id: 'n-fan', type: 'ALERT' });
  });
});

Step 8 - Offline-then-reconnect delivery

Tests for RTDB and Firestore leverage the emulator's network simulation; for WebSocket/SSE, simulate by closing the connection before events are sent:

it('delivers queued notifications after reconnect', (done) => {
  let reconnected = false;
  let client = new WebSocket(`ws://localhost:${PORT}`);

  client.once('open', () => {
    // simulate disconnect by closing the connection abruptly
    client.terminate();

    // reconnect after a short delay
    client = new WebSocket(`ws://localhost:${PORT}`);
    reconnected = true;
    client.on('message', (data) => {
      expect(reconnected).toBe(true);
      const msg = JSON.parse(data);
      expect(msg.type).toBe('QUEUED_NOTIFICATION');
      client.close();
      done();
    });
  });
});

For RTDB/Firestore, the SDK's offline write queue and the /.info/connected reconnect assertion are covered in references/firebase-listener-tests.md.

Step 9 - Ordering assertions

In-app notification streams must deliver events in consistent order, especially when multiple events are emitted in quick succession. Per the WHATWG SSE spec, MessageEvent.lastEventId tracks the sequence position and is replayed as the Last-Event-ID header on reconnect, enabling gap detection:

it('delivers notifications in emission order', (done) => {
  const received = [];
  wss.once('connection', (ws) => {
    ['n-1', 'n-2', 'n-3'].forEach((id) =>
      ws.send(JSON.stringify({ id, type: 'ACTIVITY', seq: parseInt(id.split('-')[1]) }))
    );
  });

  const client = new WebSocket(`ws://localhost:${PORT}`);
  client.on('message', (data) => {
    received.push(JSON.parse(data));
    if (received.length === 3) {
      const seqs = received.map((m) => m.seq);
      expect(seqs).toEqual([1, 2, 3]);
      client.close();
      done();
    }
  });
});

Step 10 - Test recipe checklist

For each in-app notification transport in the codebase:

1. Happy-path single-client delivery (Steps 2-5)
2. Notification store unread/read state transitions (Step 6)
3. Fan-out: N sessions receive the same event (Step 7)
4. Offline-then-reconnect: queued events arrive in order after reconnect (Step 8)
5. Ordering: rapid successive emissions arrive in sequence (Step 9)
6. Close-code / error-code handling: 1001 / 1006 for WebSocket (Step 2); HTTP 204 disabling SSE reconnection (Step 3)

Anti-patterns

Limitations

• This skill covers the notification feature layer. For WebSocket frame-level protocol tests (masking, fragmentation, opcode handling per RFC 6455 Sections 5.2-5.4) and SSE stream-format tests, use websocket-tests and server-sent-events-tests in qa-realtime-protocols.
• Firebase emulator covers most RTDB / Firestore behavior; a small set of server-side trigger behaviors (Cloud Functions fan-out) require a real Firebase project.
• SSE ordering guarantees depend on server implementation; the WHATWG spec defines client-side lastEventId tracking but does not mandate server ordering.
• WebSocket terminate() simulates abnormal closure (1006); graceful close() sends a proper close frame per RFC 6455 Section 7.

References

• RFC 6455 - The WebSocket Protocol (Sections 4.1-4.2 opening handshake, 5.2 data framing, 7.4.1 close codes)
• WHATWG HTML Living Standard - Server-Sent Events (EventSource states, lastEventId, retry, reconnection algorithm)
• Firebase RTDB - Read and Write (onValue, get, off signatures and behavior)
• Firebase RTDB - Offline Capabilities (/.info/connected, onDisconnect, offline write queue, server timestamps)
• Firebase Firestore - Listen to Real-time Updates (onSnapshot, hasPendingWrites, fromCache, latency compensation)
• Firebase Local Emulator Suite (RTDB + Firestore emulator usage for offline/reconnect testing)
• websocket-tests, server-sent-events-tests in qa-realtime-protocols - transport-layer protocol tests
• push-notification-test-author, email-flow-test-author, sms-test-author, webhook-delivery-tester
  • sibling channels this skill does not cover