jobs

README

Jobs Module Testing

Requirements

Local Development

• Docker must be running - Tests will fail with a clear error if Docker is not available
• Tests automatically start a Redis container for each test run
• No fallbacks or mocks - real Redis only

GitHub Actions

• Tests automatically use the Redis service provided by GitHub Actions
• No additional setup required - it just works

Running Tests

# Run all jobs tests (Docker must be running)
cd jobs
go test -v

# Run specific test scenarios
go test -v -run TestJobsFeatures

Test Coverage

Current coverage: ~38% of runtime.go

To view coverage report:

go test -coverprofile=coverage.out
go tool cover -html=coverage.out

Architecture

The jobs module uses Asynq for background job processing with Redis as the backend.

Test Infrastructure

• test_helpers.go - Manages Redis container lifecycle
• runtime_test.go - BDD tests using Cucumber/Godog
• redis_test.go - Simple connectivity test

Key Features Tested

• Runtime initialization with/without Redis
• Job enqueueing and processing
• Welcome email jobs
• Session cleanup jobs
• Error handling and retries
• Worker management

Docker Compose

For local development with persistent Redis:

docker-compose up -d

This starts Redis on port 6379 with data persistence.

Troubleshooting

"Docker must be running" error

Start Docker Desktop or the Docker daemon:

# macOS
open -a Docker

# Linux
sudo systemctl start docker

"Redis container failed to start" error

Check if port 6379 is already in use:

lsof -i :6379

Kill any existing Redis processes or containers:

docker ps -q --filter ancestor=redis | xargs docker stop

CI/CD

GitHub Actions workflow automatically:

1. Starts Redis service on port 6379
2. Runs all tests including jobs tests
3. Reports coverage

No special configuration needed - tests detect GHA environment and use the provided Redis service.

Documentation

Index

• func HandleCleanupSessions(ctx context.Context, t *asynq.Task) error
• func HandleEmailSend(ctx context.Context, t *asynq.Task) error
• func HandleWelcomeEmail(ctx context.Context, t *asynq.Task) error
• type Config
• type EmailPayload
• type RedisContainer
  • func StartRedisContainer() (*RedisContainer, error)
  • func (rc *RedisContainer) FlushAll() error
  • func (rc *RedisContainer) Stop() error
  • func (rc *RedisContainer) URL() string
• type Runtime
  • func NewRuntime(redisURL string) (*Runtime, error)
  • func (r *Runtime) Enqueue(taskType string, payload interface{}, opts ...asynq.Option) error
  • func (r *Runtime) EnqueueAt(at time.Time, taskType string, payload interface{}) error
  • func (r *Runtime) EnqueueEmail(to, subject, body string) error
  • func (r *Runtime) EnqueueIn(delay time.Duration, taskType string, payload interface{}) error
  • func (r *Runtime) EnqueueWelcomeEmail(userID string) error
  • func (r *Runtime) IsReady() bool
  • func (r *Runtime) RegisterDefaults()
  • func (r *Runtime) Shutdown()
  • func (r *Runtime) Start() error
  • func (r *Runtime) Stop() error

Functions

func HandleCleanupSessions

func HandleCleanupSessions(ctx context.Context, t *asynq.Task) error

HandleCleanupSessions removes expired sessions

func HandleEmailSend

func HandleEmailSend(ctx context.Context, t *asynq.Task) error

HandleEmailSend processes email sending jobs

func HandleWelcomeEmail

func HandleWelcomeEmail(ctx context.Context, t *asynq.Task) error

HandleWelcomeEmail processes welcome email jobs for new users

Types

type Config

type Config struct {
	RedisURL    string
	Concurrency int
	Queues      map[string]int // Queue priorities
}

Config holds job runtime configuration

type EmailPayload

type EmailPayload struct {
	To      string `json:"to"`
	Subject string `json:"subject"`
	Body    string `json:"body"`
}

EmailPayload represents email job data

type RedisContainer

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

RedisContainer manages a Redis Docker container for testing

func StartRedisContainer

func StartRedisContainer() (*RedisContainer, error)

StartRedisContainer starts a Redis container for testing

func (*RedisContainer) FlushAll

func (rc *RedisContainer) FlushAll() error

FlushAll clears all data from Redis

func (*RedisContainer) Stop

func (rc *RedisContainer) Stop() error

Stop stops the Redis container

func (*RedisContainer) URL

func (rc *RedisContainer) URL() string

URL returns the Redis connection URL

type Runtime

type Runtime struct {
	Client *asynq.Client
	Server *asynq.Server
	Mux    *asynq.ServeMux
	// contains filtered or unexported fields
}

Runtime encapsulates the Asynq client, server, and mux

func NewRuntime

func NewRuntime(redisURL string) (*Runtime, error)

NewRuntime creates a new job runtime

func (*Runtime) Enqueue

func (r *Runtime) Enqueue(taskType string, payload interface{}, opts ...asynq.Option) error

Enqueue adds a job to the queue

func (*Runtime) EnqueueAt

func (r *Runtime) EnqueueAt(at time.Time, taskType string, payload interface{}) error

EnqueueAt schedules a job to run at a specific time

func (*Runtime) EnqueueEmail

func (r *Runtime) EnqueueEmail(to, subject, body string) error

EnqueueEmail is a helper to enqueue an email job

func (*Runtime) EnqueueIn

func (r *Runtime) EnqueueIn(delay time.Duration, taskType string, payload interface{}) error

EnqueueIn schedules a job to run after a delay

func (*Runtime) EnqueueWelcomeEmail

func (r *Runtime) EnqueueWelcomeEmail(userID string) error

EnqueueWelcomeEmail enqueues a welcome email for a new user

func (*Runtime) IsReady

func (r *Runtime) IsReady() bool

IsReady checks if the runtime is properly initialized (has client and mux) without starting the server. This is useful for tests.

func (*Runtime) RegisterDefaults

func (r *Runtime) RegisterDefaults()

RegisterDefaults registers default job handlers

func (*Runtime) Shutdown

func (r *Runtime) Shutdown()

Shutdown gracefully stops the jobs runtime

func (*Runtime) Start

func (r *Runtime) Start() error

Start begins processing jobs

func (*Runtime) Stop

func (r *Runtime) Stop() error

Stop gracefully shuts down the job processor