How to Test and Debug a Telegram Mini App

The short version

A Mini App is a web page that runs inside Telegram's WebView. Debugging it comes down to four habits:

1. Run the app locally and expose it through an HTTPS tunnel.
2. Point a separate dev bot at that URL, so real users never see unfinished work.
3. For everyday UI work, mock the Telegram environment in a normal browser.
4. Before release, open the app in every client with WebView devtools enabled.

Running locally over an HTTPS tunnel

Telegram opens Mini Apps over HTTPS, so localhost alone will not work inside the app.

1. Start the dev server, for example on port 5173.
2. Open a tunnel: cloudflared tunnel --url http://localhost:5173 or ngrok http 5173.
3. In @BotFather, set the tunnel URL for your dev bot's Mini App or menu button.
4. Open the bot in Telegram and launch the app.

Typical snags:

• Some dev servers, Vite among them, reject requests from unknown hosts. Add the tunnel domain to the allowed hosts.
• Hot reload may need its WebSocket settings adjusted to go through the tunnel.
• Free tunnels often change the URL on every restart, which means updating BotFather each time. A reserved domain saves this step.

The Telegram test environment

Telegram runs a separate test server with its own accounts, bots and data. It is useful when you want full isolation, for example to test payments without touching production.

• iOS: tap the Settings icon 10 times, open Accounts, choose Login to another account, then Test.
• Telegram Desktop: open Settings, hold Shift + Alt and right-click Add Account, then choose Test Server.
• Create a bot with @BotFather inside the test environment. Bot API calls then go to https://api.telegram.org/bot<token>/test/METHOD.
• In the test environment, Mini App links without TLS are allowed, which simplifies local work.

For most projects, a dev bot in the regular environment is enough; the test server is an extra layer, not a requirement.

Enabling WebView debugging

Menu names can change between client versions; the official Mini Apps documentation keeps the current steps. As a fallback, an in-page console such as Eruda, loaded only in development builds, shows logs right on the phone.

Mocking initData and theme params

In a normal browser, window.Telegram.WebApp has no initData, no user and no theme. Mock them in development only:

const tg = (window as any).Telegram?.WebApp;

if (import.meta.env.DEV && !tg?.initData) {
  const theme = {
    bg_color: "#ffffff",
    text_color: "#000000",
    button_color: "#2481cc",
    button_text_color: "#ffffff",
  };
  for (const [key, value] of Object.entries(theme)) {
    document.documentElement.style.setProperty(
      `--tg-theme-${key.replace(/_/g, "-")}`,
      value,
    );
  }
}

Libraries such as @telegram-apps/sdk offer helpers to mock the whole launch environment, including the user and start parameters.

The backend is the harder part, because it validates initData with an HMAC signature based on the bot token. Two safe options: sign test initData yourself with the dev bot's token in tests, or add a dev-only bypass with a fixed test user that cannot be enabled in production.

Keep a dark theme mock too: many layout bugs appear only when colors flip.

Checking behavior across clients

• Viewport: the visible height changes when the keyboard opens; check forms at the bottom of the screen.
• Safe areas and fullscreen mode on phones with notches.
• MainButton and BackButton: visibility, text and click handlers on every screen.
• Theme switching while the app is open, via the themeChanged event.
• Links: external pages through openLink, Telegram links through openTelegramLink.
• Older clients: guard new methods with isVersionAtLeast.
• Android, iOS, Desktop, macOS and Telegram Web, on a small screen and a slow network.