GmRelayBot/tests/e2e/README.md

GmRelay E2E Tests

This module contains locally-run end-to-end tests for the GmRelay Telegram bot and Blazor/Web dashboard. It is deliberately not wired into CI because it requires real Telegram infrastructure (MTProto user client) and a running Web instance.

Status

Tracked as a Gitea milestone: E2E Automation

Issue	Title	Status
#144	initData / Login Widget helper for mock Telegram auth	✅ Done
#145	Playwright tests for Blazor dashboard with mocked Telegram auth	✅ Done
#146	Telegram user client (MTProto)	✅ Done
#147	Automate group creation and bot invitation	✅ Done
#148	Scenario: /newsession from creation to publication	✅ Done
#149	Join/leave, waitlist, reschedule and notification scenarios	✅ Done
#150	Dashboard display and editing verification	✅ Done
#151	Console runner and cleanup	⏳ Planned

Structure

tests/e2e/
├── README.md
├── requirements.txt
├── .gitignore
├── helpers/
│   ├── telegram_init_data.py      # Build valid Telegram auth payloads
│   ├── test_telegram_init_data.py # Self-contained sanity tests for the helper
│   └── __init__.py
├── dashboard/
│   ├── test_dashboard_auth_and_sessions.py  # Playwright tests for the Blazor dashboard
│   └── __init__.py
└── runner/
    ├── GmRelay.E2E.Runner.csproj   # C# console runner using WTelegramClient (MTProto)
    ├── Program.cs                  # Entry point for quick manual checks
    ├── TelegramUserClient.cs       # Reusable MTProto user client wrapper
    ├── GroupSetupScenario.cs                # Create group + invite bot + verify /start
    ├── NewSessionScenario.cs                # Walk the /newsession wizard end-to-end
    ├── JoinLeaveWaitlistRescheduleScenario.cs # Join, waitlist, promotion, leave, reschedule, notifications
    ├── DatabaseAssertions.cs                # Query PostgreSQL and seed fake participants
    ├── RunnerConfig.cs                      # Configuration model
    ├── .env.example                         # Required environment variables
    ├── .gitignore                           # Ignore .env and session files
    └── packages.lock.json                   # Restored lock file for the runner project

Install dependencies

Python (dashboard tests)

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r tests/e2e/requirements.txt
playwright install chromium

C# runner (MTProto)

dotnet restore tests/e2e/runner/GmRelay.E2E.Runner.csproj

Run helper tests

python tests/e2e/helpers/test_telegram_init_data.py

Run Playwright dashboard tests

1. Start the Web dashboard (and PostgreSQL) locally. The fastest way:

   dotnet run --project src/GmRelay.AppHost/GmRelay.AppHost.csproj
   

2. Export environment variables that match the running Web instance:

   export GMRELAY_E2E_BASE_URL="http://localhost:8080"
   export GMRELAY_E2E_BOT_TOKEN="<same-token-as-web>"
   export GMRELAY_E2E_TELEGRAM_ID="9000000001"
   export GMRELAY_E2E_DATABASE_URL="Host=localhost;Database=gmrelay;Username=postgres;Password=<password>"
   

3. Run the tests:

   python tests/e2e/dashboard/test_dashboard_auth_and_sessions.py
   

Run the MTProto user client runner

The runner logs in to a real Telegram user account, creates a supergroup, invites the test bot, sends /start, waits for a reply, and deletes the group.

1. Copy the example environment file and fill in real values:

   cp tests/e2e/runner/.env.example tests/e2e/runner/.env
   

2. Edit tests/e2e/runner/.env with your Telegram api_id, api_hash, phone_number, the bot username/token, and Web URL.
3. Run:

   dotnet run --project tests/e2e/runner/GmRelay.E2E.Runner.csproj
   

Security notes:

• Never commit .env or *.session files.
• Use a dedicated test Telegram account, never your personal or production account.
• The first run will prompt for the Telegram verification code (sent to the phone number).
• Subsequent runs reuse the persisted .session file.

What the dashboard tests cover

• test_dashboard_authenticates_and_shows_groups
  Builds a valid Mini App initData payload, posts it to /auth/telegram-webapp, and verifies that the Blazor home page renders the authenticated greeting.
• test_dashboard_session_edit_flow
  Seeds a player, group, and session directly in PostgreSQL, opens the group details page, navigates to the session editor, changes the title, join link and max players, asserts the updated values appear on the page, and verifies the persisted database state.
• test_dashboard_session_delete_flow
  Seeds a session, opens the group details page, confirms the deletion dialog, asserts the session disappears from the dashboard, and verifies the session was removed from PostgreSQL.

What the MTProto runner currently covers

• Login as a Telegram user.
• Create a supergroup (Channels_CreateChannel with megagroup: true).
• Resolve a bot by username and invite it to the group.
• Send /start to the bot inside the group and wait for any reply.
• Walk /newsession from start to published schedule message.
• Join/leave a session via inline buttons and assert the database state.
• Join into a waitlist when the active roster is full (using a seeded fake participant).
• Manually promote a waitlisted player via /listsessions and verify promotion.
• Leave an active session and verify automatic promotion of the next waitlisted player.
• Initiate a reschedule, propose 2-3 time options, vote, and wait for the background deadline service to apply the new time.
• Exercise T-24h RSVP confirmation and T-5m join-link reminders by time-travelling sessions.scheduled_at from the runner (database-level time-mock).
• Delete the test supergroup after the scenario (cleanup).

Notes

• Authentication is mocked using helpers/telegram_init_data.py, which mirrors GmRelay.Shared.Telegram.TelegramAuthPayloadBuilder.
• The Web instance validates HMAC-SHA256 with the same bot token, so the test payload is indistinguishable from a real Telegram Mini App payload.
• The runner project is intentionally not included in GM-Relay.slnx so it does not participate in CI builds or Native AOT trimming.
• The Telegram lifecycle scenario uses one real test account plus fake participants seeded directly into PostgreSQL, and a database-level time-mock (UPDATE sessions SET scheduled_at = ...) so 24-hour and 5-minute reminders fire in minutes instead of hours. This is the locally-runnable approach chosen for issue #149.
• For headful debugging, change headless=True to headless=False in the dashboard test file.