@crvouga/mockingbird-service-slack

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of Slack for test suites: incoming webhooks, the Web API methods our apps call, and the Socket Mode control plane Bolt needs in order to boot, with an outbox of everything the app "sent". A suite asserts that an alert fired (GET /__admin/outbox?webhook=… or ?channel=…) without a real workspace, and drives the retry paths (429 with retry-after, 5xx) and the terminal ones (no_text, no_service, channel_not_found) with named presets.

• Operation coverage: SUPPORT.md
• Slack publishes no maintained OpenAPI for these methods: the contract (openapi.yaml) is hand-authored from Slack's documented wire shapes and our consumers.

Install

npm install -D @crvouga/mockingbird-service-slack

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-slack serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Point every SLACK_*_WEBHOOK_URL (SLACK_PIPELINE_ALERT_WEBHOOK_URL, SLACK_ERX_ALERTS_WEBHOOK_URL, SLACK_BILLING_ALERT_WEBHOOK_URL, SLACK_CRITICAL_ALERT_WEBHOOK_URL, RECONCILER_SLACK_WEBHOOK_URL, …) at http://127.0.0.1:8808/services/T000/B000/<anything>. Any path is accepted until you register hooks. The Web API callers hardcode https://slack.com/api/…; point them at http://127.0.0.1:8808/api/… (for @slack/web-api, slackApiUrl: "http://127.0.0.1:8808/api/"). Bolt in Socket Mode uses that same clientOptions.slackApiUrl (Bolt copies it into SocketModeReceiver) plus an xapp- app token. apps.connections.open returns a ws:// URL on this process.

npx mockingbird-slack serve --port 8808

import { IncomingWebhook } from "@slack/webhook"
import { WebClient } from "@slack/web-api"
import { createServer } from "@crvouga/mockingbird-service-slack/server"

const server = await createServer()

// The app's own Slack clients. Only the URLs they are given change.
const webhook = new IncomingWebhook(`${server.url}/services/T000/B000/XXXX`)
await webhook.send({ text: "reconcile failed", blocks: [{ type: "divider" }] }) // { text: "ok" }
const slack = new WebClient("xoxb-fixture", { slackApiUrl: `${server.url}/api/` })
await slack.chat.postMessage({ channel: "#alerts", text: "deploy finished" }) // { ok: true, ts, … }

// Test controls. Make the next post fail the way Slack does under load; our clients retry at 0/2/8 s.
server.runtime.applyPreset("rate_limited", "default", { count: 1 })

const outbox = await fetch(`${server.url}/__admin/outbox?webhook=/services/T000/B000/XXXX`)
// { messages: [{ text: "reconcile failed", blocks: [...], ts: "1700000000.000001", thread_ts: null, … }] }
await server.close()

Routes

Web API bodies may be JSON or form-encoded (structures JSON-encoded in form fields), as Slack accepts both; read methods also take query arguments. Auth is Authorization: Bearer xox… (or a token form field): missing → not_authed, anything but an xoxb-/xoxp-/xoxa- token (or one outside settings.tokens) → invalid_auth. Logical errors are HTTP 200 {ok: false, error}; a JSON post without charset succeeds with Slack's missing_charset warning.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n, "params"?: {...}}):

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on the webhook URL or API base, or by credential: PUT /__admin/credentials {"credentials": {"xoxb-worker-a": "a", "T000/B000/XXXX": "b"}} maps a bot token or a webhook's T/B/X path to a namespace.

Deliberately not modelled

• Inbound Events API and interactivity delivery. Socket Mode's connection lifecycle is modelled (apps.connections.open, hello, ping/pong, disconnect) so Bolt can boot and shut down; the emulator does not push events on connect. A disconnect envelope has no reconnect URL, matching Slack's documented shape and @slack/[email protected], which calls apps.connections.open again.
• File uploads and downloads: files.info answers seeded metadata; the files.slack.com URLs are not served.
• Real per-method rate-limit tiers: 429s come only from the rate_limited preset.
• Channel membership rules for posting (not_in_channel), chat:write.public scopes, and trigger-id expiry for views.open.
• Message formatting (mrkdwn parsing, link unfurling, mention resolution): text and blocks are stored verbatim.
• Block Kit limits are a best guess, not oracle-verified (from the per-block pages on docs.slack.dev; the exact status and message Slack returns for each rule was never observed live). blocks and each attachments[].blocks are rejected as invalid_blocks (webhook: 400 invalid_blocks; chat.postMessage, chat.update, chat.postEphemeral: 200 {ok: false, error: "invalid_blocks", response_metadata: {messages}}, the messages being the emulator's own wording) when: there are more than 50 blocks (in each array; whether Slack applies 50 inside attachments is unconfirmed); a block's type is not a Block Kit block type; a section text is over 3000 characters or its fields are over 10 items or 2000 characters each; a header text is not plain_text or is over 150 characters; context has over 10 elements or actions over 25; a block_id is over 255 characters; a text object is empty. Exactly-at-limit values are accepted and stored verbatim, and a rejected message stores nothing (an update leaves the original untouched). Required-field rules (a section with neither text nor fields, an image without alt_text), element-level validation inside actions / context / input / rich_text, and the other attachment fields are not modelled.

API

Part of mockingbird.