simcord 0.1.0__tar.gz

simcord-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,17 @@
+---
+name: Bug report
+about: Something behaves differently than real Discord, or crashes
+labels: bug
+---
+
+**What happened?**
+
+**Minimal failing test** (the perfect bug report is a test using `simcord`):
+
+```python
+```
+
+**Versions**: simcord, discord.py, Python
+
+**Checked the [parity matrix](https://simcord.readthedocs.io/parity-matrix/)?**
+If the feature is listed as unimplemented, please use the parity gap template instead.

simcord-0.1.0/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,12 @@
+---
+name: Feature request
+about: New testing API, assertion helper, or framework capability
+labels: enhancement
+---
+
+**The problem you're trying to solve**:
+
+**Proposed API** (sketch the test you'd like to be able to write):
+
+```python
+```

simcord-0.1.0/.github/ISSUE_TEMPLATE/parity-gap.md

@@ -0,0 +1,11 @@
+---
+name: Parity gap
+about: My bot needs an API route or Discord behavior the virtual backend doesn't implement
+labels: parity
+---
+
+**The route or feature** (paste the `RouteNotImplemented` message if you have one):
+
+**What your bot does with it**:
+
+**How you'd want to drive/assert it from a test**:

simcord-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

simcord-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run ruff check src tests examples
+      - run: uv run ruff format --check src tests examples
+      - run: uv run pyright src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run coverage run -m pytest tests examples -q
+      - run: uv run coverage report
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra docs
+      - run: uv run mkdocs build --strict

simcord-0.1.0/.github/workflows/dpy-master.yml

@@ -0,0 +1,22 @@
+# Early warning for discord.py internal changes: run the suite against the
+# upstream development branch every week (and on demand).
+name: discord.py master
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: |
+          uv sync --extra dev
+          uv pip install -U "discord.py @ git+https://github.com/Rapptz/discord.py"
+      - run: uv run pytest tests examples -q

simcord-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run pytest tests examples -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing (no token secrets)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      # Pinned to a commit SHA (v1.14.0) rather than the mutable release/v1
+      # branch: this job holds id-token: write, so a moved tag/branch could be
+      # used to mint a trusted-publishing token.
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b

simcord-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Virtual environments
+.venv/
+venv/
+
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+
+# Editors
+.idea/
+.vscode/
+
+# Local agent/planning files (not part of the project)
+PLAN.md
+.claude/
+site/

simcord-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

simcord-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

simcord-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+This changelog is generated with [towncrier](https://towncrier.readthedocs.io/).
+
+<!-- towncrier release notes start -->
+
+## 0.1.0 (2026-06-12)
+
+### Features
+
+- Added `env.advance_time(seconds)`: fast-forward the virtual clock so view timeouts fire, cooldowns reset, and `asyncio.sleep` chains complete — instantly, with no real waiting. The event-loop clock and message timestamps advance together.
+- Added `env.raise_errors()`, which re-raises everything the bot raised during the test (command handlers, app-command callbacks, event listeners) as an `ExceptionGroup` — a one-call way to assert the bot ran cleanly. Does nothing when no errors were captured.
+- Failing tests now automatically include a transcript of everything that crossed the two seams — gateway events injected and REST calls the bot made, in order — attached by the pytest plugin. Also available programmatically as `env.transcript()`.
+- Uninspected bot errors now fail the test: `dpt.run` re-raises captured errors as an `ExceptionGroup` at teardown unless the test read `env.errors` or called `env.raise_errors()`. Opt out with `dpt.run(bot, check_errors=False)`.
+
+### Bug fixes
+
+- A deferred component interaction (callback type 6) followed by `edit_original_response` now edits the clicked message in place, matching real Discord, instead of creating a new message. `@original` for a type-6 defer also resolves to the component's source message.
+- An interaction is now marked acknowledged only after its callback is handled successfully, so a callback that 400s (e.g. an oversized embed) no longer consumes the interaction — a retried response gets through instead of a spurious `40060`.
+- DMing a bot now opens the channel successfully and fails on send with `403 50007` (caught by `except discord.Forbidden`), matching Discord. Ephemeral messages no longer leak into the bot-facing channel history and pins endpoints, and webhook-authored messages now carry `webhook_id`.
+- Serialized timestamps now come from the same virtual clock as snowflakes, so a message's `created_at` (derived from its id) and its `timestamp` agree instead of differing by months, and timestamps are deterministic across runs.
+- Tightened server-side permission parity: the bot can no longer edit another user's message (`50005`), assign/edit roles at or above its own top role or grant permissions it lacks (`50013`), or delete the `@everyone` role. `mention_everyone` is only set when the author actually has the permission.
+- Unimplemented routes now raise `RouteNotImplemented` directly rather than as a `discord.HTTPException`, so a bot's broad `except discord.HTTPException` can no longer silently swallow the "not implemented" signal. `history(around=...)` is now supported.
+- `Env.settle()` now waits out `asyncio.sleep`-style pauses in handlers (cooldowns, backoff) instead of returning early, and only abandons tasks genuinely parked on a future. Assertions after an actor verb no longer race against a handler that paused before replying.
+
+### Miscellaneous
+
+- CI hardening: pinned the PyPI publish action to a commit SHA, added a test gate before release publishing, and set default `contents: read` permissions on the CI workflows.
+- Centralised the Discord wire-protocol magic numbers (interaction, callback, option and component types) into `IntEnum`s in `simcord.enums`, replacing scattered bare integer constants in the actors, payload builders and interaction route.
+- Dropped Python 3.10 support; the minimum is now Python 3.11.
+- Every state mutation now lives on `Backend` paired with its own gateway emit (channel/overwrite edits, member field/role edits, role edits), and route handlers parse, permission-check via the new `ctx.require_channel_permissions`/`ctx.require_guild_permissions` helpers, then call a single backend method. This removes the copy-pasted permission preamble and the "mutate then remember to announce" pattern, so a write can't be announced inconsistently or forgotten as route coverage grows.
+- Setup and not-implemented errors now attach supporting detail (available options, the parity-matrix pointer) as exception notes, keeping the primary message tight while still surfacing the context in tracebacks.
+- The interaction response lifecycle is now a typed `Interaction` dataclass with a `ResponseKind` enum, replacing the untyped dict that was mutated across the route, actor, and result layers. `InteractionResult` no longer exposes the raw `.record` dict; use its typed properties (`acknowledged`, `deferred`, `ephemeral`, `modal`, `response`, `followups`) instead.
+- The parity matrix's route inventory is now generated from the route table (`python -m simcord.parity`) and guarded by a sync test, so it is exact by construction. Also: `Backend` is no longer in `__all__` (still importable, documented as internal/unstable), and CI now enforces a coverage floor.

simcord-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful, be constructive, assume good faith. Harassment and personal
+attacks are not tolerated.
+
+Report unacceptable behavior to the maintainers via GitHub.

simcord-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for helping make Discord bot testing better!
+
+## Development setup
+
+The project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/SilentHacks/simcord
+cd simcord
+uv sync --extra dev
+uv run pytest tests examples
+uv run ruff check src tests examples && uv run ruff format --check src tests examples
+uv run pyright src
+```
+
+## Project layout
+
+- `src/simcord/backend/` — the virtual Discord: dataclass models, wire-format
+  serializers (annotated against `discord.types`), the permissions engine, error catalog,
+  in-memory CDN, and the central `Backend` store.
+- `src/simcord/http/` — the route table and per-resource REST handlers, plus the
+  fake `HTTPClient`/webhook adapter.
+- `src/simcord/gateway.py` — feeds payloads into discord.py's real parsers.
+- `src/simcord/{env,builders,actors,results,interactions}.py` — the public API.
+- `src/simcord/_dpy_internals.py` — **every** touch of a private discord.py API,
+  behind an import-time self-check. New private-API usage goes here, nowhere else.
+
+## Guidelines
+
+- **Fidelity first.** The backend must behave like real Discord: real error codes, real
+  validation limits, real payload shapes. When in doubt, check the
+  [Discord API docs](https://discord.com/developers/docs) and discord.py's
+  `discord.types` definitions.
+- **Never fake success silently.** Unimplemented routes must raise `RouteNotImplemented`.
+- Every new route or feature needs an integration test in `tests/integration/` driving
+  the sample bot (`tests/fixtures/sample_bot/`) through it, plus a parity-matrix update:
+  run `uv run python -m simcord.parity docs/parity-matrix.md` to regenerate the
+  route inventory (a unit test enforces it), and update the curated feature table by hand.
+  Pure backend logic (permissions, routing) gets unit tests in `tests/unit/`.
+- New state mutations live on `Backend`, paired with their gateway emit; route handlers
+  parse, permission-check (`ctx.require_*_permissions`), call one backend method, and
+  serialize.
+- Public API lives on `Env` and the handle objects — no module-global state.
+- Add a towncrier news fragment in `changes/` for user-visible changes
+  (e.g. `changes/42.feature.md`).
+
+## Reporting bugs
+
+A failing test using `simcord` is the perfect bug report. If your bot hits an
+unimplemented route, the error message names it — include that in the issue.

simcord-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SilentHacks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simcord-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: simcord
+Version: 0.1.0
+Summary: SimCord — discord.py testing framework. Simulate Discord, test your bot offline: no network, no token, no ToS.
+Project-URL: Homepage, https://github.com/SilentHacks/simcord
+Project-URL: Documentation, https://simcord.readthedocs.io/
+Project-URL: Issues, https://github.com/SilentHacks/simcord/issues
+Project-URL: Changelog, https://github.com/SilentHacks/simcord/blob/master/CHANGELOG.md
+Author: SilentHacks
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bot testing,discord,discord.py,integration testing,mock,mock discord,pytest,simulator,testing,unit testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: discord-py<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: towncrier>=24; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: pytest
+Requires-Dist: pytest-asyncio>=0.24; extra == 'pytest'
+Requires-Dist: pytest>=8; extra == 'pytest'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# SimCord
+
+**The discord.py testing framework — simulate Discord, test your bot offline.**
+
+Test your discord.py bot with a full virtual Discord environment: no network, no token,
+no test server, no Terms of Service concerns. SimCord is the missing testing library
+for discord.py bots.
+
+[![CI](https://github.com/SilentHacks/simcord/actions/workflows/ci.yml/badge.svg)](https://github.com/SilentHacks/simcord/actions/workflows/ci.yml)
+[![Docs](https://app.readthedocs.org/projects/simcord/badge/?version=latest)](https://simcord.readthedocs.io/)
+[![PyPI](https://img.shields.io/pypi/v/simcord)](https://pypi.org/project/simcord/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/simcord/)
+[![discord.py](https://img.shields.io/badge/discord.py-2.7%2B-5865F2)](https://github.com/Rapptz/discord.py)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[Quickstart](#quickstart) · [Documentation](https://simcord.readthedocs.io/) · [Parity matrix](https://simcord.readthedocs.io/parity-matrix/) · [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+SimCord is a **discord.py testing framework** that 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:
+
+```python
+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!"
+```
+
+> ⚠️ **Alpha.** The core surface (messages, prefix commands, slash commands, components,
+> modals, permissions, reactions, threads, DMs, time control) works; see the
+> [parity matrix](https://simcord.readthedocs.io/parity-matrix/) for the
+> long tail. Unimplemented routes always fail loudly — SimCord never silently fakes
+> success.
+
+## Why SimCord?
+
+Unit tests cover your business logic, but the bugs that bite Discord bots live in the
+glue: converters, checks, permissions, forgotten `tree.sync()` calls, double-acknowledged
+interactions, oversized embeds. Until now the only way to test that layer was manually,
+in a real server. SimCord runs all of discord.py's real machinery — its parsers, cache,
+command frameworks and views — against a faithful mock of Discord's REST API and gateway,
+entirely in-process.
+
+|  |  |
+| --- | --- |
+| 🎯 **Real discord.py semantics** | Server-side permission checks with authentic error codes (`50013 Missing Permissions`…), interaction lifecycle rules (`40060` on double-ack), role hierarchy, timeouts, ephemeral visibility, validation limits. |
+| 🐛 **Real bugs caught** | Invoking a never-synced slash command fails your test, just like production. Clicking a disabled button is impossible, just like the client. Unhandled bot errors fail the test by default. |
+| ⚡ **Fast & deterministic** | No sleeps, no network, reproducible IDs and timestamps. The framework tracks the bot's tasks and settles after every action. |
+| ⏩ **Time control** | `env.advance_time(180)` fires view timeouts and resets cooldowns instantly — no real waiting. |
+| 🔍 **Debuggable failures** | Failing tests automatically include a transcript of every gateway event and REST call — exactly what your bot did, in order. |
+| 📢 **Loud gaps** | Anything not implemented raises `RouteNotImplemented` naming the route. Never silent fake success. |
+
+## Install
+
+```bash
+pip install simcord[pytest]
+```
+
+Requires Python 3.11+ and discord.py 2.7+. Zero dependencies beyond discord.py itself.
+
+## Quickstart
+
+Tell the bundled pytest plugin how to build your bot:
+
+```python
+# 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:
+
+```python
+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
+```
+
+Buttons, selects, modals, context menus, autocomplete, reactions, threads, DMs, fault
+injection and more: see the [documentation](https://simcord.readthedocs.io/).
+Prefer explicit control? `async with simcord.run(bot) as env:` works in any async
+test framework.
+
+## 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 code running unmodified.
+
+```
+test ──► builders/actors ──► virtual backend (single source of truth)
+                                   │                     │
+                  gateway payloads ▼                     ▼ REST responses
+                  ConnectionState.parsers        FakeHTTPClient route table
+                                   │                     ▲
+                                   ▼                     │
+                                  your real, unmodified bot
+```
+
+Details in the [architecture docs](https://simcord.readthedocs.io/architecture/).
+
+## discord.py testing — common use cases
+
+SimCord covers the full range of discord.py bot testing scenarios:
+
+- **discord.py unit testing** — test individual commands in isolation
+- **discord.py integration testing** — test full command flows with permissions, roles and channels
+- **discord.py mock events** — fire any gateway event (member join, reaction add, voice state…) without a real server
+- **discord.py mock Discord** — a full in-memory Discord server your bot can't tell from the real thing
+- **discord.py command testing** — prefix commands, slash commands, context menus, autocomplete
+- **discord.py interaction testing** — buttons, selects, modals, ephemeral responses, deferred replies
+- **discord.py bot testing without a token** — no `.env`, no test guild, no rate limits
+
+## Comparison
+
+| | SimCord | dpytest | Manual test server |
+|---|---|---|---|
+| No network / no token | ✅ | ✅ | ❌ |
+| Real discord.py internals | ✅ | Partial | ✅ |
+| Slash commands & components | ✅ | ❌ | ✅ |
+| Authentic error codes | ✅ | ❌ | ✅ |
+| Time control | ✅ | ❌ | ❌ |
+| Failure transcripts | ✅ | ❌ | ❌ |
+| Maintained for discord.py 2.x | ✅ | ❌ | — |
+
+## Contributing
+
+See [CONTRIBUTING.md](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](https://github.com/SilentHacks/simcord/issues/new?template=parity-gap.md).
+
+## License
+
+[MIT](LICENSE). Unofficial — not affiliated with Discord Inc. or the discord.py project.