test(handlers): integration tests + recording bot + emulator on CI

Phase 5 of the 2026-05-09 review remediation plan. Closes the
handler-layer test gap (5 modules at 0% coverage in the audit) and
ends the storage-package's CI t.Skip on Firestore emulator tests.

- internal/testutil: Update fixture builders (NewPrivateMessage,
  NewGroupMessage, NewSupergroupMessage, NewChannelMessage) plus a
  RecordingBot that wraps the real go-telegram/bot.Bot with an
  httptest server. The bot library hits the test server instead of
  Telegram; multipart form fields are captured per call. Tests assert
  on Sent() / LastSent() / AssertSentText().
- Handler tests added: misc (4), util (7), wordle (10), loldle (9),
  loldleemoji (8). Cover happy paths, error paths, auth gates,
  group-vs-private subject keying, KV side effects.
- Coverage 44.7% -> 69.8% (verified via -coverprofile). All packages
  now report coverage in CI output.
- CI: ci.yml installs cloud-firestore-emulator beta component and
  starts it on localhost:8090 before go test. Sets
  FIRESTORE_EMULATOR_HOST + GOOGLE_CLOUD_PROJECT env so the storage
  package's emulator-gated tests execute instead of skipping.

go test -race -count=1 ./... clean across all 15 packages locally.

internal/modules/loldle/handlers_test.go

@@ -0,0 +1,153 @@
+package loldle
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/tiennm99/miti99bot-go/internal/modules"
+	"github.com/tiennm99/miti99bot-go/internal/storage"
+	"github.com/tiennm99/miti99bot-go/internal/testutil"
+)
+
+// installLoldle wires the loldle module + auth (owner gates /loldle_setmax,
+// which is private). seedTarget pre-seeds a game so guess outcomes are
+// deterministic without hooking math/rand.
+func installLoldle(t *testing.T, ownerID int64, seedSubject, seedTarget string) (*testutil.RecordingBot, storage.KVStore) {
+	t.Helper()
+	rb := testutil.NewRecordingBot(t)
+	provider := storage.NewMemoryProvider()
+	kv := provider.For("loldle")
+	mod := New(modules.Deps{KV: kv})
+	reg := &modules.Registry{
+		Modules:     []modules.Module{{Name: "loldle", Commands: mod.Commands}},
+		AllCommands: map[string]modules.Command{},
+	}
+	for _, c := range mod.Commands {
+		reg.AllCommands[c.Name] = c
+	}
+	modules.Install(rb.Bot, reg, modules.Auth{BotOwnerID: ownerID})
+
+	if seedTarget != "" {
+		g := &gameState{Target: seedTarget, Guesses: []string{}}
+		if err := saveGame(context.Background(), kv, seedSubject, g); err != nil {
+			t.Fatalf("seed game: %v", err)
+		}
+	}
+	return rb, kv
+}
+
+func TestLoldle_NoArgShowsBoard(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Guess 0/") {
+		t.Errorf("/loldle no-arg reply missing 'Guess 0/...': %q", got)
+	}
+}
+
+func TestLoldle_Win(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle aatrox"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(strings.ToLower(got), "aatrox") {
+		t.Errorf("win reply missing 'Aatrox': %q", got)
+	}
+	if !strings.Contains(got, "🎉") {
+		t.Errorf("win reply missing celebration emoji: %q", got)
+	}
+}
+
+func TestLoldle_UnknownChampion(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle ZilbeanZ"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Champion not found") {
+		t.Errorf("unknown champion reject: %q", got)
+	}
+}
+
+func TestLoldle_DuplicateGuessRejected(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "1", "Aatrox")
+	// First guess: Ahri (not the target — round continues).
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle ahri"))
+	rb.Reset()
+	// Second guess: Ahri again — duplicate path.
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle ahri"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "already guessed") {
+		t.Errorf("duplicate-guess reply: %q", got)
+	}
+}
+
+func TestLoldleGiveup_RevealsAnswer(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_giveup"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Aatrox") {
+		t.Errorf("/loldle_giveup should reveal Aatrox: %q", got)
+	}
+}
+
+func TestLoldleGiveup_NoActiveRound(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_giveup"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "No active round") {
+		t.Errorf("/loldle_giveup with no round: %q", got)
+	}
+}
+
+func TestLoldleStats_Empty(t *testing.T) {
+	rb, _ := installLoldle(t, 0, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_stats"))
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"Played: 0", "Wins: 0 (0%)", "Best streak: 0"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("/loldle_stats empty missing %q; got %q", want, got)
+		}
+	}
+}
+
+func TestLoldleSetMax_OwnerSucceeds(t *testing.T) {
+	rb, kv := installLoldle(t, 999, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/loldle_setmax 5"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "max guesses set to 5") {
+		t.Errorf("/loldle_setmax reply: %q", got)
+	}
+	var cfg roundConfig
+	if err := kv.GetJSON(context.Background(), configKey("999"), &cfg); err != nil {
+		t.Fatalf("expected config persisted: %v", err)
+	}
+	if cfg.MaxGuesses != 5 {
+		t.Errorf("MaxGuesses persisted = %d, want 5", cfg.MaxGuesses)
+	}
+}
+
+func TestLoldleSetMax_DeniedToNonOwner(t *testing.T) {
+	rb, _ := installLoldle(t, 999, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(7, "/loldle_setmax 5"))
+
+	if calls := rb.Sent(); len(calls) != 0 {
+		t.Errorf("non-owner /loldle_setmax replied: %+v", calls)
+	}
+}
+
+func TestLoldleSetMax_RejectsOutOfRange(t *testing.T) {
+	rb, _ := installLoldle(t, 999, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/loldle_setmax 99"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Usage:") {
+		t.Errorf("out-of-range setmax should show usage; got %q", got)
+	}
+}

internal/modules/loldleemoji/handlers_test.go

@@ -0,0 +1,130 @@
+package loldleemoji
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/tiennm99/miti99bot-go/internal/modules"
+	"github.com/tiennm99/miti99bot-go/internal/storage"
+	"github.com/tiennm99/miti99bot-go/internal/testutil"
+)
+
+// installEmoji wires the loldle-emoji module + auth (owner gates
+// /loldle_emoji_setmax). seedTarget pre-seeds a game so guess outcomes are
+// deterministic without hooking math/rand.
+func installEmoji(t *testing.T, ownerID int64, seedSubject, seedTarget string) (*testutil.RecordingBot, storage.KVStore) {
+	t.Helper()
+	rb := testutil.NewRecordingBot(t)
+	provider := storage.NewMemoryProvider()
+	kv := provider.For("loldle-emoji")
+	mod := New(modules.Deps{KV: kv})
+	reg := &modules.Registry{
+		Modules:     []modules.Module{{Name: "loldle-emoji", Commands: mod.Commands}},
+		AllCommands: map[string]modules.Command{},
+	}
+	for _, c := range mod.Commands {
+		reg.AllCommands[c.Name] = c
+	}
+	modules.Install(rb.Bot, reg, modules.Auth{BotOwnerID: ownerID})
+
+	if seedTarget != "" {
+		g := &gameState{Target: seedTarget, Guesses: []string{}}
+		if err := saveGame(context.Background(), kv, seedSubject, g); err != nil {
+			t.Fatalf("seed game: %v", err)
+		}
+	}
+	return rb, kv
+}
+
+func TestEmoji_NoArgShowsClue(t *testing.T) {
+	rb, _ := installEmoji(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "🎭") {
+		t.Errorf("emoji clue marker missing: %q", got)
+	}
+}
+
+func TestEmoji_Win(t *testing.T) {
+	rb, _ := installEmoji(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji aatrox"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Got it") {
+		t.Errorf("win reply missing 'Got it': %q", got)
+	}
+	if !strings.Contains(got, "Aatrox") {
+		t.Errorf("win reply missing 'Aatrox': %q", got)
+	}
+}
+
+func TestEmoji_UnknownChampion(t *testing.T) {
+	rb, _ := installEmoji(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji ZilbeanZ"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Champion not found") {
+		t.Errorf("unknown champion reject: %q", got)
+	}
+}
+
+func TestEmoji_DuplicateGuessRejected(t *testing.T) {
+	rb, _ := installEmoji(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji ahri"))
+	rb.Reset()
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji ahri"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "already guessed") {
+		t.Errorf("duplicate-guess reply: %q", got)
+	}
+}
+
+func TestEmojiGiveup_RevealsAnswer(t *testing.T) {
+	rb, _ := installEmoji(t, 0, "1", "Aatrox")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji_giveup"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Aatrox") {
+		t.Errorf("/loldle_emoji_giveup should reveal Aatrox: %q", got)
+	}
+}
+
+func TestEmojiStats_Empty(t *testing.T) {
+	rb, _ := installEmoji(t, 0, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/loldle_emoji_stats"))
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"Played: 0", "Wins: 0 (0%)"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("/loldle_emoji_stats empty missing %q; got %q", want, got)
+		}
+	}
+}
+
+func TestEmojiSetMax_OwnerSucceeds(t *testing.T) {
+	rb, kv := installEmoji(t, 999, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/loldle_emoji_setmax 7"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "max guesses set to 7") {
+		t.Errorf("/loldle_emoji_setmax reply: %q", got)
+	}
+	var cfg roundConfig
+	if err := kv.GetJSON(context.Background(), configKey("999"), &cfg); err != nil {
+		t.Fatalf("expected config persisted: %v", err)
+	}
+	if cfg.MaxGuesses != 7 {
+		t.Errorf("MaxGuesses persisted = %d, want 7", cfg.MaxGuesses)
+	}
+}
+
+func TestEmojiSetMax_DeniedToNonOwner(t *testing.T) {
+	rb, _ := installEmoji(t, 999, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(7, "/loldle_emoji_setmax 5"))
+	if calls := rb.Sent(); len(calls) != 0 {
+		t.Errorf("non-owner /loldle_emoji_setmax replied: %+v", calls)
+	}
+}

internal/modules/misc/handlers_test.go

@@ -0,0 +1,103 @@
+package misc
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/tiennm99/miti99bot-go/internal/modules"
+	"github.com/tiennm99/miti99bot-go/internal/storage"
+	"github.com/tiennm99/miti99bot-go/internal/testutil"
+)
+
+// installMisc wires the misc module to a recording bot with a fresh
+// in-memory KV. Returns the bot, the kv (so tests can pre-seed or read),
+// and an Auth that permits Owner + Admin so /mstats /fortytwo dispatch.
+func installMisc(t *testing.T, ownerID int64) (*testutil.RecordingBot, storage.KVStore) {
+	t.Helper()
+	rb := testutil.NewRecordingBot(t)
+	provider := storage.NewMemoryProvider()
+	kv := provider.For("misc")
+	mod := New(modules.Deps{KV: kv})
+
+	reg := &modules.Registry{
+		Modules:     []modules.Module{{Name: "misc", Commands: mod.Commands}},
+		AllCommands: map[string]modules.Command{},
+	}
+	for _, c := range mod.Commands {
+		reg.AllCommands[c.Name] = c
+	}
+	auth := modules.Auth{BotOwnerID: ownerID}
+	modules.Install(rb.Bot, reg, auth)
+	return rb, kv
+}
+
+func TestPing_RepliesPongAndWritesKV(t *testing.T) {
+	rb, kv := installMisc(t, 999)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/ping"))
+
+	if got := rb.LastSent().Text(); got != "pong" {
+		t.Errorf("ping reply = %q, want %q", got, "pong")
+	}
+	var stored lastPing
+	if err := kv.GetJSON(context.Background(), lastPingKey, &stored); err != nil {
+		t.Fatalf("expected lastPing in KV: %v", err)
+	}
+	if stored.At <= 0 {
+		t.Errorf("lastPing.At = %d, want positive", stored.At)
+	}
+	// Sanity: timestamp is within a minute of now (rules out stale fixture).
+	if delta := time.Now().UTC().UnixMilli() - stored.At; delta > 60_000 || delta < 0 {
+		t.Errorf("lastPing.At delta from now = %dms, want within 60s", delta)
+	}
+}
+
+func TestMstats_NeverWhenKVEmpty(t *testing.T) {
+	rb, _ := installMisc(t, 999)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/mstats"))
+
+	if got := rb.LastSent().Text(); got != "last ping: never" {
+		t.Errorf("mstats reply = %q, want 'last ping: never'", got)
+	}
+}
+
+func TestMstats_AfterPing(t *testing.T) {
+	rb, _ := installMisc(t, 999)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/ping"))
+	rb.Reset()
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/mstats"))
+
+	got := rb.LastSent().Text()
+	if !strings.HasPrefix(got, "last ping: ") {
+		t.Errorf("mstats reply = %q, want 'last ping: ...'", got)
+	}
+	if strings.Contains(got, "never") {
+		t.Errorf("mstats still says 'never' after /ping: %q", got)
+	}
+}
+
+func TestMstats_DeniedToNonAdmin(t *testing.T) {
+	rb, _ := installMisc(t, 999) // owner = 999
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(7, "/mstats"))
+
+	if calls := rb.Sent(); len(calls) != 0 {
+		t.Errorf("non-admin /mstats produced replies: %+v", calls)
+	}
+}
+
+func TestFortytwo_OwnerOnly(t *testing.T) {
+	rb, _ := installMisc(t, 999)
+
+	// Non-owner: silent denial
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(7, "/fortytwo"))
+	if calls := rb.Sent(); len(calls) != 0 {
+		t.Errorf("non-owner /fortytwo replied: %+v", calls)
+	}
+
+	// Owner: reply
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/fortytwo"))
+	if got := rb.LastSent().Text(); got != "The answer." {
+		t.Errorf("owner /fortytwo reply = %q, want 'The answer.'", got)
+	}
+}

internal/modules/util/handlers_test.go

@@ -0,0 +1,119 @@
+package util_test
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/go-telegram/bot/models"
+
+	"github.com/tiennm99/miti99bot-go/internal/modules"
+	"github.com/tiennm99/miti99bot-go/internal/modules/util"
+	"github.com/tiennm99/miti99bot-go/internal/storage"
+	"github.com/tiennm99/miti99bot-go/internal/testutil"
+)
+
+// installUtil builds a registry with the util module + auth that admits the
+// supplied owner so /stickerid (private) dispatches.
+func installUtil(t *testing.T, ownerID int64) *testutil.RecordingBot {
+	t.Helper()
+	rb := testutil.NewRecordingBot(t)
+	reg, err := modules.Build([]string{"util"},
+		map[string]modules.Factory{"util": util.New},
+		storage.NewMemoryProvider(), nil)
+	if err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+	modules.Install(rb.Bot, reg, modules.Auth{BotOwnerID: ownerID})
+	return rb
+}
+
+func TestInfo_PrivateChat(t *testing.T) {
+	rb := installUtil(t, 0)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(42, "/info"))
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"chat id: 42", "thread id: n/a", "sender id: 42"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("info reply missing %q; got %q", want, got)
+		}
+	}
+}
+
+func TestInfo_GroupChat(t *testing.T) {
+	rb := installUtil(t, 0)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewGroupMessage(-100, 7, "/info"))
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"chat id: -100", "sender id: 7"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("info reply missing %q; got %q", want, got)
+		}
+	}
+}
+
+func TestInfo_ChannelMessageNoFrom(t *testing.T) {
+	rb := installUtil(t, 0)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewChannelMessage(-200, "/info"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "sender id: n/a") {
+		t.Errorf("info channel reply missing 'sender id: n/a'; got %q", got)
+	}
+}
+
+func TestHelp_RendersHTML(t *testing.T) {
+	rb := installUtil(t, 0)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/help"))
+
+	calls := rb.Sent()
+	if len(calls) == 0 {
+		t.Fatal("/help produced no reply")
+	}
+	got := calls[len(calls)-1]
+	if got.Form["parse_mode"] != string(models.ParseModeHTML) {
+		t.Errorf("/help parse_mode = %q, want HTML", got.Form["parse_mode"])
+	}
+	if !strings.Contains(got.Text(), "<b>util</b>") {
+		t.Errorf("/help body missing util section; got %q", got.Text())
+	}
+}
+
+func TestStickerID_NoReply_ShowsUsage(t *testing.T) {
+	rb := installUtil(t, 999)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(999, "/stickerid"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Reply to a sticker") {
+		t.Errorf("stickerid usage missing; got %q", got)
+	}
+}
+
+func TestStickerID_WithStickerReply_EchoesFileID(t *testing.T) {
+	rb := installUtil(t, 999)
+	upd := testutil.NewPrivateMessage(999, "/stickerid")
+	upd.Message.ReplyToMessage = &models.Message{
+		Sticker: &models.Sticker{
+			FileID:       "AAA-file-id",
+			FileUniqueID: "uniq",
+			SetName:      "TestSet",
+			Emoji:        "🎉",
+		},
+	}
+	rb.Bot.ProcessUpdate(context.Background(), upd)
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"AAA-file-id", "uniq", "TestSet", "🎉"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("stickerid reply missing %q; got %q", want, got)
+		}
+	}
+}
+
+func TestStickerID_DeniedToNonOwner(t *testing.T) {
+	rb := installUtil(t, 999)
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(7, "/stickerid"))
+	if calls := rb.Sent(); len(calls) != 0 {
+		t.Errorf("non-owner /stickerid replied: %+v", calls)
+	}
+}

internal/modules/wordle/handlers_test.go

@@ -0,0 +1,166 @@
+package wordle
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/tiennm99/miti99bot-go/internal/modules"
+	"github.com/tiennm99/miti99bot-go/internal/storage"
+	"github.com/tiennm99/miti99bot-go/internal/testutil"
+)
+
+// installWordle wires the wordle module to a recording bot with an
+// in-memory KV. seedTarget pre-seeds a game with the supplied target
+// (skip dictionary randomness for deterministic tests). Empty seedTarget
+// leaves the KV blank so handlers spin up a fresh round on first call.
+func installWordle(t *testing.T, ownerID int64, seedSubject, seedTarget string) (*testutil.RecordingBot, storage.KVStore) {
+	t.Helper()
+	rb := testutil.NewRecordingBot(t)
+	provider := storage.NewMemoryProvider()
+	kv := provider.For("wordle")
+	mod := New(modules.Deps{KV: kv})
+	reg := &modules.Registry{
+		Modules:     []modules.Module{{Name: "wordle", Commands: mod.Commands}},
+		AllCommands: map[string]modules.Command{},
+	}
+	for _, c := range mod.Commands {
+		reg.AllCommands[c.Name] = c
+	}
+	modules.Install(rb.Bot, reg, modules.Auth{BotOwnerID: ownerID})
+
+	if seedTarget != "" {
+		g := &GameState{Target: seedTarget, Guesses: []GuessRecord{}, StartedAt: 1}
+		if err := saveGame(context.Background(), kv, seedSubject, g); err != nil {
+			t.Fatalf("seed game: %v", err)
+		}
+	}
+	return rb, kv
+}
+
+func TestWordle_NoArgShowsBoard(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Guess 0/6") {
+		t.Errorf("/wordle empty-arg reply missing 'Guess 0/6': %q", got)
+	}
+}
+
+func TestWordle_Win(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle crane"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Solved in 1/6") {
+		t.Errorf("win reply missing 'Solved in 1/6': %q", got)
+	}
+	if !strings.Contains(got, "Streak: 1") {
+		t.Errorf("win reply missing 'Streak: 1': %q", got)
+	}
+}
+
+func TestWordle_InvalidWord_TooShort(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle hi"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "5 letters") {
+		t.Errorf("short-word reject missing length hint: %q", got)
+	}
+}
+
+func TestWordle_InvalidWord_NotInDict(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle qqqqq"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Not in the word list") {
+		t.Errorf("dict-miss reject wrong text: %q", got)
+	}
+}
+
+func TestWordle_PartialGuessShowsProgress(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	// "crate" shares 4 letters with "crane" — valid 5-letter dictionary word.
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle crate"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "Guess 1/6") {
+		t.Errorf("partial-guess reply missing 'Guess 1/6': %q", got)
+	}
+}
+
+func TestWordleNew_StartsFreshRound(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle_new"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "New round started") {
+		t.Errorf("/wordle_new reply: %q", got)
+	}
+	// Previous round was active (no guesses yet) → auto-giveup prelude expected.
+	if !strings.Contains(got, "Previous round abandoned") {
+		t.Errorf("/wordle_new should announce auto-giveup of prior active round; got %q", got)
+	}
+}
+
+func TestWordleGiveup_RevealsAnswer(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle_giveup"))
+
+	got := rb.LastSent().Text()
+	if !strings.Contains(got, "CRANE") {
+		t.Errorf("/wordle_giveup should reveal CRANE; got %q", got)
+	}
+}
+
+func TestWordleStats_Empty(t *testing.T) {
+	rb, _ := installWordle(t, 0, "", "")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle_stats"))
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"Played: 0", "Wins: 0 (0%)", "Best streak: 0"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("/wordle_stats missing %q; got %q", want, got)
+		}
+	}
+}
+
+func TestWordleStats_AfterWin(t *testing.T) {
+	rb, _ := installWordle(t, 0, "1", "crane")
+	// Win: produces 1 played, 1 win, streak 1.
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle crane"))
+	rb.Reset()
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewPrivateMessage(1, "/wordle_stats"))
+
+	got := rb.LastSent().Text()
+	for _, want := range []string{"Played: 1", "Wins: 1 (100%)", "Current streak: 1"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("/wordle_stats post-win missing %q; got %q", want, got)
+		}
+	}
+}
+
+// Group chats key by chat id, so two private users both writing /wordle
+// in the same group must mutate the same game.
+func TestWordle_GroupSubjectIsChatID(t *testing.T) {
+	rb, kv := installWordle(t, 0, "-100", "crane")
+	rb.Bot.ProcessUpdate(context.Background(), testutil.NewGroupMessage(-100, 7, "/wordle crate"))
+
+	// After one guess in chat -100, subject "-100" should have a guess
+	// recorded; subject "7" should have no game.
+	var gChat GameState
+	if err := kv.GetJSON(context.Background(), gameKey("-100"), &gChat); err != nil {
+		t.Fatalf("expected game at subject=-100: %v", err)
+	}
+	if len(gChat.Guesses) != 1 {
+		t.Errorf("group game has %d guesses, want 1", len(gChat.Guesses))
+	}
+	var gUser GameState
+	err := kv.GetJSON(context.Background(), gameKey("7"), &gUser)
+	if err == nil {
+		t.Errorf("user-keyed game leaked despite group context: %+v", gUser)
+	}
+}