Mock & Testing

The mock feature installs a configurable fake Telegram.WebApp object on window, so you can develop and test outside the Telegram client. Enable it:

telegram-webapp-sdk = { version = "0.11", features = ["mock"] }

Installing a mock environment

The mock lives under telegram_webapp_sdk::mock. Build a MockTelegramConfig (it implements Default) and call mock_telegram_webapp, which injects window.Telegram.WebApp with mocked initData, themeParams, platform, and version. Use it only in debug builds.

use telegram_webapp_sdk::mock::{config::MockTelegramConfig, init::mock_telegram_webapp};

fn run() -> Result<(), wasm_bindgen::JsValue> {
let config = MockTelegramConfig::default();
mock_telegram_webapp(config)?;
// window.Telegram.WebApp now exists — the SDK behaves as if inside Telegram.
Ok(())
}

Customizing the mocked data

MockTelegramConfig exposes optional fields for the user, auth data, every theme color, and the platform/version. A mocked user is a MockTelegramUser:

use telegram_webapp_sdk::mock::{
    config::MockTelegramConfig, data::MockTelegramUser, init::mock_telegram_webapp,
};

fn run() -> Result<(), wasm_bindgen::JsValue> {
let config = MockTelegramConfig {
    user: Some(MockTelegramUser {
        id: 42,
        first_name: "Alice".into(),
        username: Some("alice".into()),
        language_code: Some("en".into()),
        ..Default::default()
    }),
    platform: Some("android".into()),
    version: Some("9.6".into()),
    ..Default::default()
};
mock_telegram_webapp(config)?;
Ok(())
}

You can also load the config from a TOML file (the same telegram-webapp.toml that telegram_app! reads in debug builds):

use telegram_webapp_sdk::mock::config::MockTelegramConfig;

let config = MockTelegramConfig::from_file("telegram-webapp.toml")?;
Ok::<(), std::io::Error>(())

Testing with wasm_bindgen_test

Because the SDK talks to browser globals, tests run in a headless browser via wasm-bindgen-test. Add it as a dev-dependency:

[dev-dependencies]
wasm-bindgen-test = "0.3"

Configure the tests to run in a browser and install the mock before exercising the SDK:

use telegram_webapp_sdk::{
    core::init::init_sdk,
    mock::{config::MockTelegramConfig, init::mock_telegram_webapp},
    webapp::TelegramWebApp,
};
use wasm_bindgen_test::{wasm_bindgen_test, wasm_bindgen_test_configure};

wasm_bindgen_test_configure!(run_in_browser);

#[wasm_bindgen_test]
fn instance_is_available_after_mock() {
    mock_telegram_webapp(MockTelegramConfig::default()).expect("mock installed");
    init_sdk().expect("sdk initialized");

    let app = TelegramWebApp::instance().expect("instance");
    app.ready().expect("ready");
}

Run the suite against a real browser engine:

# Chrome / Chromium
wasm-pack test --headless --chrome

# or Firefox
wasm-pack test --headless --firefox

Tips

• Prefer TelegramWebApp::instance() (returning Option) in app code so the same binary degrades gracefully when neither Telegram nor the mock is present.
• Each wasm_bindgen_test shares one window; install the mock at the start of every test that needs it rather than relying on ordering.
• Note that TelegramContext::init succeeds only once per thread — design tests so they do not depend on re-initializing the global context.

See also

• Quick Start — the code you are testing
• Examples — the examples/vanilla app builds with the mock feature