GramLab

Original Android capture, with glass effects enabled.

Test Telegram bots locally and inspect their messages in the actual Telegram Android client. No Telegram account or production token is needed.

Experimental. Text, callbacks, rich messages, photos, documents, albums and custom emoji have tested original-Android workflows. A persistent playground supports seeded state, a visible and clickable original Android client, messages, rich-button input, bot addition and reset. Mini Apps, HTML parse modes, grouped-media edits, external Telegram conformance and native Telegram membership administration remain unfinished. See the compatibility matrix for the supported scope.

Install

GramLab currently requires Python 3.13 on a supported Linux host. Install the experimental prerelease explicitly:

uv add "gramlab==0.1.0a1"

The package includes the gramlab command and typed Python scenario interface. Android captures require separately prepared local tooling and are not distributed in the Python package.

Write a scenario

Create a user, talk to a real local bot, check its reply and capture the conversation:

from gramlab import Scenario

lab = Scenario.from_environment()
chat = lab.conversation(user=lab.user("Alex", language_code="en"), bot="echo")
chat.send("Hello!")
history = chat.wait_for_messages(2, timeout=5)

if history[1].text != "Echo: Hello!":
    raise AssertionError("Unexpected bot reply")
chat.capture("hello", contains=["Echo: Hello!"])

This runs inside a scenario process. The English echo example uses this exact scenario, with the bundled bot and manifest, and the runner supplies the environment. Simulation records the conversation state; headless Android also captures the original client. Both modes produce a local HTML report. The typed handles are additive: advanced scenarios can still use the raw JSON-shaped operations on Scenario. The Python interface is still experimental.

Try it

Start with the development environment. On a supported Linux host with Nix and user namespaces:

nix develop
uv sync --locked
mkdir -p artifacts
uv run --locked --offline gramlab run examples/echo/hello.toml --output artifacts/echo-demo

Open artifacts/echo-demo/report.html. Use a new output directory for each run. The runner isolates bot and scenario processes; dependency setup happens before execution. Android captures require the separate Android setup.

More examples: button presses, rich messages, rich buttons, and bot restart.

Work on GramLab

• Contributor setup and checks
• Current handoff and remaining work
• Architecture and product scope
• Offline execution rules
• Working in parallel
• Release history

Original core and SDK code uses MIT. Two TDLib-derived Python modules retain BSL-1.0. Android-derived patches and fixtures retain GPL-2.0-or-later. See the license map and licensing boundaries. This is a source repository. No Android APK release or completed dependency license audit is offered.

GramLab is unofficial and is not affiliated with or endorsed by Telegram.