golagramtest

Documentation

Overview

Package golagramtest provides first-class testing support for bots built on golagram. The usage pattern:

server := golagramtest.NewServer()
defer server.Close()

bot := golagramtest.NewBot(t, server)
bot.Dispatch(router) // required — HandleUpdate matches nothing without it

bot.HandleUpdate(context.Background(), golagramtest.CommandMessage(1, 2, "start"))

calls := server.CallsTo("sendMessage")

Server is a fake Bot API backed by net/http/httptest; NewBot wires a real gg.TelegramBot at it (including the startup getMe call NewTelegramBot always makes). TextMessage, CommandMessage, and CallbackQueryUpdate build synthetic updates to feed to gg.TelegramBot.HandleUpdate, which dispatches synchronously — no StartWorkers/Run/RunWebhook needed.

Index

• func CallbackQueryUpdate(chatID, userID int64, data string) *gg.Update
• func CommandMessage(chatID, userID int64, command string, args ...string) *gg.Update
• func NewBot(t *testing.T, server *Server, opts ...gg.Option) *gg.TelegramBot
• func TextMessage(chatID, userID int64, text string) *gg.Update
• type Call
  • func (c Call) Decode(v any) error
• type Server
  • func NewServer(opts ...ServerOption) *Server
  • func (s *Server) Calls() []Call
  • func (s *Server) CallsTo(method string) []Call
  • func (s *Server) Close()
  • func (s *Server) Fail(method string, code int, description string)
  • func (s *Server) LastCall() (Call, bool)
  • func (s *Server) Reset()
  • func (s *Server) Respond(method string, result any)
  • func (s *Server) URL() string
• type ServerOption
  • func WithBotUser(u *gg.User) ServerOption

Functions

func CallbackQueryUpdate

func CallbackQueryUpdate(chatID, userID int64, data string) *gg.Update

CallbackQueryUpdate builds an *gg.Update carrying a callback query with the given data, including an attached originating gg.Message so handlers that read cq.Message (chat ID, message ID for edits, ...) work.

func CommandMessage

func CommandMessage(chatID, userID int64, command string, args ...string) *gg.Update

CommandMessage builds an *gg.Update carrying "/command arg1 arg2" — matching what gg.ParseCommand/gg.FilterCommand expect.

func NewBot

func NewBot(t *testing.T, server *Server, opts ...gg.Option) *gg.TelegramBot

NewBot builds a gg.TelegramBot pointed at server, applying opts after gg.WithBaseURL(server.URL()) so callers can still pass their own WithFSMStorage/WithLogger/etc. Fails the test via t.Fatalf if construction errors (e.g. server isn't answering getMe correctly).

func TextMessage

func TextMessage(chatID, userID int64, text string) *gg.Update

TextMessage builds an *gg.Update carrying a plain text message from userID in chatID, ready for gg.TelegramBot.HandleUpdate.

Types

type Call

type Call struct {
	Method string
	Body   json.RawMessage
}

Call is one recorded request against a Server.

func (Call) Decode

func (c Call) Decode(v any) error

Decode unmarshals the call's raw request body into v, e.g. call.Decode(&map[string]any{}). Decoding straight into a generated request type such as gg.SendMessageRequest fails for any request carrying a gg.ChatID field — it has no UnmarshalJSON — so prefer a map or a narrower ad hoc struct over the request type itself.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is a fake Telegram Bot API backed by an httptest.Server. Point a bot at it with gg.WithBaseURL(server.URL()) — NewBot does this for you — then inspect what the bot sent via Server.Calls/Server.CallsTo/ Server.LastCall, or script its replies via Server.Respond/ Server.Fail.

Every unconfigured method defaults to returning a synthetic gg.Message (not a bare true): the hand-written Answer/Reply sugar strictly decodes its result as a Message, unlike generated methods, which tolerate either shape — defaulting to Message keeps the common case (asserting on a reply) working without per-test setup. If you're testing a method whose return value actually matters and isn't a Message — DeleteMessage, SetChatTitle, and other bool-returning calls — configure it explicitly:

server.Respond("deleteMessage", true)

func NewServer

func NewServer(opts ...ServerOption) *Server

NewServer starts a fake Bot API server. Call Server.Close when done.

func (*Server) Calls

func (s *Server) Calls() []Call

Calls returns every recorded call, in request order.

func (*Server) CallsTo

func (s *Server) CallsTo(method string) []Call

CallsTo returns the recorded calls to method, in request order.

func (*Server) Close

func (s *Server) Close()

Close shuts down the underlying HTTP server.

func (*Server) Fail

func (s *Server) Fail(method string, code int, description string)

Fail configures method to return a Telegram-shaped API error ({"ok":false,"error_code":code,"description":description}). Sticky, like Server.Respond.

func (*Server) LastCall

func (s *Server) LastCall() (Call, bool)

LastCall returns the most recently recorded call, or false if none has happened yet.

func (*Server) Reset

func (s *Server) Reset()

Reset clears every recorded call and configured override, back to a freshly-built Server's defaults (getMe still pre-wired).

func (*Server) Respond

func (s *Server) Respond(method string, result any)

Respond configures method to return result as a successful API response. The override is sticky — it applies to every future call to method until changed by another Respond/Fail or cleared by Server.Reset.

func (*Server) URL

func (s *Server) URL() string

URL returns the base URL to pass to gg.WithBaseURL. NewBot does this automatically.

type ServerOption

type ServerOption func(*Server)

ServerOption configures a Server built by NewServer.

func WithBotUser

func WithBotUser(u *gg.User) ServerOption

WithBotUser overrides the gg.User returned for getMe (default: a generic test bot). NewTelegramBot calls getMe once at construction, so this is what a bot built via NewBot sees as its own identity.