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

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.