mastodon-mock 0.4.0

Stateful in-memory/SQLite mock of the Mastodon REST API for testing Mastodon clients

Mastodon Mock

mastodon_mock is a stateful, local Mastodon REST API for tests and development. It runs a real FastAPI server backed by in-memory or file-backed SQLite, so client code can post statuses, follow accounts, build timelines, manage lists and filters, file reports, and exercise OAuth/admin flows without touching a live instance.

Use it when you want the confidence of real HTTP and persisted state, without flaky network tests, rate limits, public test posts, or hand-written response mocks.

Highlights:

• Real Mastodon-shaped HTTP API, tested against Mastodon.py.
• Fast disposable SQLite state, with deterministic seed data and reset support.
• Pytest fixtures, a context manager, and decorator sugar for zero-boilerplate tests.
• Bulk sample-data generation for demos, UI work, and performance checks.
• Bundled web client and admin UI at /_ui/ when the package includes the built frontend.
• Admin/moderation endpoints for account actions, reports, domain blocks, email blocks, and IP blocks.

Installation

pipx install mastodon_mock

Or with pip:

pip install mastodon_mock

Usage

Run the mock server:

mastodon_mock serve --in-memory

Point a client at it:

from mastodon import Mastodon

client = Mastodon(access_token="mock_token", api_base_url="http://127.0.0.1:3000")
client.status_post("hello from a mock!")

Open http://127.0.0.1:3000/_ui/ for the bundled browser UI when it is available. The UI covers timelines, compose/reply, boost/favourite/bookmark, quote posts, threads, profiles, search, lists, an About this server page (instance rules, terms of service, custom emojis), an announcements banner (dismiss + emoji reactions), and an admin panel (accounts, reports, domains, announcements, trends).

For a quick, good-looking demo with a small community already populated — multiple accounts, follows, a quote post, announcements, rules, and terms of service — run:

mastodon_mock serve --in-memory --demo

For a populated local instance, generate a throwaway cohort into a SQLite file and point your config's [database].path at it:

mastodon_mock gen-data --preset small --database ./mastodon_mock.sqlite --yes

HTTPS (required for most Mastodon clients, e.g. Whalebird, Fedistar)

Desktop/mobile Mastodon clients connect to the entered domain over HTTPS regardless of any scheme you type, so pointing one at a plain-HTTP serve instance fails with Invalid HTTP request received in the server log (the client's TLS handshake hitting an HTTP parser).

A plain openssl self-signed cert is often not enough — Electron-based clients (Whalebird, Fedistar) commonly refuse to connect at all rather than warn-and-allow like a browser does. Use mkcert instead: it installs a local CA into your OS trust store and issues certs signed by it, so clients trust the connection outright.

make dev-cert      # generates .dev_certs/ via mkcert if installed, else falls back to openssl
make serve-https    # dev-cert + serve --in-memory --demo --port 3443 over HTTPS

Or run the steps by hand:

mkcert -install   # one-time: adds a local CA to the OS/browser trust stores
mkcert -key-file .dev_certs/localhost-key.pem -cert-file .dev_certs/localhost-cert.pem \
  localhost 127.0.0.1 ::1

mastodon_mock serve --in-memory --demo --port 3443 \
  --ssl-keyfile .dev_certs/localhost-key.pem --ssl-certfile .dev_certs/localhost-cert.pem

Point the client at https://127.0.0.1:3443 (or localhost). Without mkcert installed, gen-dev-cert.sh falls back to an openssl self-signed cert, but expect Electron clients to refuse it outright rather than just warn.

See HTTPS and Real Mastodon Clients for the full walkthrough (mkcert setup, troubleshooting, and how serve derives a reachable domain for avatar/header/status URLs).

Tested on...

• Tuba - Works, but had to use port 443 and edit hosts file so cert matched domain (mock.local in my case)
• Whalebird- Works!
• Fedistar - couldn't get it to trust local certificate
• Dowstodon - Works!
• Various web - They need to make a serverside request to my machine. Can't do it, without putting a mock server on public web.
• toot - can't test on Windows
• Sengi - couldn't get this to work? But not sure the Sengi app is finished either (as of 6/2026)?

Documentation

See the documentation for configuration, fixtures, endpoint coverage, data generation, and admin UI/API details.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.

Changelog

See CHANGELOG.md.