SimCord gives your bot a fake but faithful Discord to run against. Simulate users sending messages, invoking slash commands, clicking buttons and submitting modals, then assert on exactly what your bot did. It all runs in-process, with no network and no token.

async def test_ping(simcord_env):
    channel = simcord_env.create_guild().create_text_channel("general")
    alice = simcord_env.guild.add_member(simcord_env.create_user("alice"))

    await alice.send(channel, "!ping")          # full gateway round trip

    assert channel.last_message.content == "Pong!"

The bundled example bot is executable, tested, and covers prefix commands, slash commands, permissions, cooldowns, modals, buttons, and persistent views.

Why SimCord?

Your unit tests cover your business logic. The bugs that actually break Discord bots live in the glue: converters, checks, permissions, a forgotten tree.sync(), a double-acknowledged interaction, an oversized embed. That layer has historically only been testable by hand, in a real server.

SimCord runs discord.py's real machinery, including its parsers, cache, command frameworks and views, against an in-memory model of Discord's REST API and gateway. Your bot code runs unmodified and can't tell the difference.

Install

python -m pip install "simcord[pytest]"

Or with uv:

uv add --dev "simcord[pytest]"

Requires Python >=3.11 (tested on 3.11–3.14) and discord.py >=2.7.1,<3. The locked CI matrix tests discord.py 2.7.1; a separate weekly workflow runs against upstream master, rather than continuously testing every released 2.x version. No dependencies beyond discord.py itself.

Quickstart

Tell the bundled pytest plugin how to build your bot:

# conftest.py
import pytest
from mybot import create_bot   # however your project builds its commands.Bot

@pytest.fixture
def simcord_bot():
    return create_bot()

Then write tests against the simcord_env fixture. It hands you a running environment with the bot already logged in and at READY:

import discord

async def test_ban_slash_command(simcord_env):
    guild = simcord_env.create_guild()
    channel = guild.create_text_channel("mod")
    mods = guild.create_role("Mods", permissions=discord.Permissions(ban_members=True))
    mod = guild.add_member(simcord_env.create_user("mod"), roles=[mods])
    target = guild.add_member(simcord_env.create_user("spammer"))

    result = await mod.slash(channel, "ban", user=target, reason="spam")

    assert result.ephemeral
    assert result.response.content == f"Banned {target.mention}: spam"
    assert guild.get_ban(target) is not None

async def test_offer_expires(simcord_env):
    channel = simcord_env.create_guild().create_text_channel("general")
    alice = simcord_env.guild.add_member(simcord_env.create_user("alice"))

    result = await alice.slash(channel, "offer")    # bot replies with a View(timeout=180)
    await simcord_env.advance_time(180)             # instant; the view times out

    assert "expired" in channel.last_message.content

Not using pytest? async with simcord.run(bot) as env: gives you the same env in any async test framework.

AI coding agents

Give Claude Code, Codex, Copilot, Cursor, or another coding agent a deterministic Discord runtime instead of letting it invent mocks that confirm its own assumptions.

Add this requirement to the task:

Use SimCord for the behavioral test. Drive the real bot through a user action,
keep the test offline, and never use a Discord token. Assert the user-visible
response and resulting Discord state, then run the focused test and project gates.

The AI coding agent guide includes a project-instructions block, a complete workflow, and the mistakes agents should avoid.

The mental model

Every SimCord test is three moves: arrange the world, act as a user, assert the result. Three kinds of object map to those moves.

import discord

async def test_welcome_on_join(simcord_env):
    guild   = simcord_env.create_guild()                       # builder
    welcome = guild.create_text_channel("welcome")             # builder
    newbie  = guild.add_member(simcord_env.create_user("ann")) # builder; fires the join event

    assert f"Welcome {newbie.mention}" in welcome.last_message.content   # query

Two details that make tests robust:

• Actors wait for the bot to finish reacting. Each verb settles the loop, running callbacks and draining asyncio.sleep chains before returning, so the reply is already there when the next line runs. No sleeps, no flakes. If a handler hangs, settling fails fast with the pending tasks listed.
• Impossible setups raise SetupError, not a bot failure. Speaking in a channel a user can't see, or clicking a disabled button, points at your test, distinct from a bug in the bot.

See Core concepts for the full picture.

What you can test

Responses come back as a rich InteractionResult exposing acknowledged, deferred, ephemeral, response, followups and modal. Threads, permissions, role hierarchy, intents and audit logs are modelled too. The parity matrix records exactly what's implemented.

Configuration & diagnostics

Pass options to simcord.run(bot, ...), or per-test via the @pytest.mark.simcord(...) marker on the simcord_env fixture:

Bot work remains owned across recognized external waits, timeout, cancellation, and restart. Declare exactly one intentional external wait with await env.external_wait(awaitable, reason="..."); unknown waits time out with diagnostics. Operations overlap-guard before mutating the virtual world, and teardown cancels bot-owned work without cancelling caller tasks.

@pytest.mark.simcord(strict_sync=False)
async def test_unsynced_command(simcord_env):
    ...

Sharded bots use discord.py's normal API. Configure AutoShardedBot with its production shard_count, then place test guilds with env.create_guild(shard_id=...). bot.shards, get_shard(), shard readiness, presence and guild event routing behave normally.

When something goes wrong, the env tells you what happened:

• env.transcript(): the ordered log of gateway events and REST calls, auto-attached to failing pytest tests.
• env.http_log: every REST request the bot made, to assert on or inspect.
• env.errors: exceptions the bot swallowed.
• env.inject_error("POST", "/channels/*/messages", status=500): make matching REST calls fail, to test your bot's error handling.
• env.restart_bot(): restart the bot while the virtual world persists, to prove persistent views re-attach.

How it works

discord.py has two narrow seams: every REST call funnels through HTTPClient.request, and every gateway event enters through ConnectionState.parsers. SimCord replaces the first with a fake routed to an in-memory backend, a single source of truth for guilds, channels, members, messages, commands and interactions, and injects Discord-shaped payloads through the second. Everything between those seams, which is everything your bot touches, is real discord.py running unmodified.

test ──► builders/actors ──► virtual backend (single source of truth)
                                   │                     │
                  gateway payloads ▼                     ▼ REST responses
                  ConnectionState.parsers        FakeHTTPClient route table
                                   │                     ▲
                                   ▼                     │
                                  your real, unmodified bot

More in the architecture docs.

SimCord vs. the alternatives

Documentation

Contributing

See CONTRIBUTING.md. Bug reports with a failing test are gold. If your bot hits an unimplemented route, the error names it. Please open a parity gap issue.

License

MIT. Unofficial and not affiliated with Discord Inc. or the discord.py project.