mastodon-mock 0.2.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

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.