Add unit tests across mongo, stats, webui, and benchmark; introduce integration test foundation; add docker-based mongo smoke test setup and docs

Author: daniel-percona

README.md

@@ -83,6 +83,10 @@ Download the [`config.yaml`](./config.yaml) and make the necessary adjustments.
   ./bin/plgm --webui
   ```
 
+### 4. Testing
+
+For unit and integration test instructions (including Docker-based MongoDB setup), see [`TESTING.md`](./TESTING.md).
+
 ## The Interactive UI
 
 `plgm` features a completely embedded Web UI. It allows you to configure your database connection, upload custom workload schemas, adjust operation ratios, and monitor real-time throughput and latency without ever touching a YAML file. It has the same functionality as the CLI version, but with an awesome UI.
@@ -1010,4 +1014,4 @@ Further configuration and examples specific to [Kubernetes environments setup wi
 
 # Disclaimer
 
-This application is not supported by Percona. It has been provided as a community contribution and is not covered under any Percona services agreement.
+This application is not supported by Percona. It has been provided as a community contribution and is not covered under any Percona services agreement.

TESTING.md

@@ -0,0 +1,70 @@
+# Testing Guide
+
+This repository has two test layers:
+
+1. Unit tests (default, fast, no MongoDB required)
+2. Integration tests (optional, require a real MongoDB instance)
+
+## Unit Tests
+
+Run all unit tests:
+
+```bash
+go test ./...
+```
+
+Unit tests are the default and are intentionally independent of local MongoDB availability.
+
+## Integration Tests
+
+Integration tests are behind the `integration` build tag and are skipped from default runs.
+
+Current integration smoke test:
+
+- `internal/mongo/TestRunWorkloadIntegration_OneShotExecutesFindUpdateAndSkipsInsert`
+
+### Option A: Start MongoDB with Docker Compose (recommended)
+
+From repository root:
+
+```bash
+docker compose -f docker-compose.integration.yml up -d
+```
+
+Then run the integration smoke test:
+
+```bash
+go test -tags=integration ./internal/mongo -run TestRunWorkloadIntegration_OneShotExecutesFindUpdateAndSkipsInsert -v
+```
+
+Stop MongoDB when done:
+
+```bash
+docker compose -f docker-compose.integration.yml down -v
+```
+
+### Option B: Use an existing MongoDB endpoint
+
+Set the URI via environment variable:
+
+```bash
+PLGM_IT_MONGO_URI='mongodb://127.0.0.1:30777' \
+go test -tags=integration ./internal/mongo -run TestRunWorkloadIntegration_OneShotExecutesFindUpdateAndSkipsInsert -v
+```
+
+If your MongoDB requires authentication, include credentials in `PLGM_IT_MONGO_URI`.
+
+## Run Everything Available
+
+```bash
+# 1) Unit tests
+go test ./...
+
+# 2) Integration smoke test(s)
+go test -tags=integration ./internal/mongo -run TestRunWorkloadIntegration_OneShotExecutesFindUpdateAndSkipsInsert -v
+```
+
+## CI Notes (Optional)
+
+- Keep `go test ./...` as the required fast gate.
+- Run `-tags=integration` tests in a separate optional/extended CI job with Docker services.

docker-compose.integration.yml

@@ -0,0 +1,12 @@
+services:
+  mongo:
+    image: mongo:7
+    container_name: plgm-it-mongo
+    ports:
+      - "30777:27017"
+    command: ["--bind_ip_all"]
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.runCommand({ ping: 1 }).ok"]
+      interval: 2s
+      timeout: 2s
+      retries: 20

internal/benchmark/runner_test.go

@@ -0,0 +1,80 @@
+package benchmark
+
+import (
+	"bytes"
+	"testing"
+	"unicode"
+)
+
+func TestGeneratePayload(t *testing.T) {
+	tests := []struct {
+		name string
+		size int
+		want int
+	}{
+		{name: "zero_uses_default", size: 0, want: 1024},
+		{name: "negative_uses_default", size: -10, want: 1024},
+		{name: "custom_size", size: 64, want: 64},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			payload := GeneratePayload(tc.size)
+			if len(payload) != tc.want {
+				t.Fatalf("expected payload size %d, got %d", tc.want, len(payload))
+			}
+		})
+	}
+}
+
+func TestGenerateRandomString(t *testing.T) {
+	if got := GenerateRandomString(0); got != "" {
+		t.Fatalf("expected empty string for size 0, got %q", got)
+	}
+
+	s := GenerateRandomString(32)
+	if len(s) != 32 {
+		t.Fatalf("expected len 32, got %d", len(s))
+	}
+	for _, r := range s {
+		if !unicode.IsDigit(r) && !unicode.IsLetter(r) {
+			t.Fatalf("expected alphanumeric characters only, got %q", string(r))
+		}
+	}
+}
+
+func TestBuildBatchArray(t *testing.T) {
+	template := []byte{0x11, 0x22, 0x33}
+	magic := []byte{0x22}
+	arr, offsets, err := buildBatchArray(template, 4, magic)
+	if err != nil {
+		t.Fatalf("buildBatchArray() error = %v", err)
+	}
+	if len(offsets) != 4 {
+		t.Fatalf("expected 4 offsets, got %d", len(offsets))
+	}
+	for _, off := range offsets {
+		if off < 0 || off >= len(arr) {
+			t.Fatalf("invalid offset %d", off)
+		}
+		if !bytes.Equal(arr[off:off+1], magic) {
+			t.Fatalf("offset %d does not point to magic byte", off)
+		}
+	}
+
+	_, _, err = buildBatchArray(template, 1, []byte{0xFF})
+	if err == nil {
+		t.Fatalf("expected error when magic byte is absent")
+	}
+
+	arr, offsets, err = buildBatchArray(template, 0, magic)
+	if err != nil {
+		t.Fatalf("buildBatchArray(count=0) error = %v", err)
+	}
+	if len(offsets) != 0 {
+		t.Fatalf("expected no offsets for empty batch, got %d", len(offsets))
+	}
+	if len(arr) == 0 {
+		t.Fatalf("expected valid BSON bytes for empty batch")
+	}
+}

internal/config/collections_test.go

@@ -0,0 +1,105 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestParseCollectionsBytes(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		wantLen int
+		wantErr bool
+	}{
+		{
+			name:    "wrapped_format",
+			input:   `{"collections":[{"database":"db1","collection":"c1","fields":{}}]}`,
+			wantLen: 1,
+		},
+		{
+			name:    "array_format",
+			input:   `[{"database":"db2","collection":"c2","fields":{}}]`,
+			wantLen: 1,
+		},
+		{
+			name:    "invalid_format",
+			input:   `{"collections":[]}`,
+			wantErr: true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseCollectionsBytes([]byte(tc.input))
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("parseCollectionsBytes() error = %v", err)
+			}
+			if len(got.Collections) != tc.wantLen {
+				t.Fatalf("expected %d collections, got %d", tc.wantLen, len(got.Collections))
+			}
+		})
+	}
+}
+
+func TestLoadCollectionsDirectoryFiltering(t *testing.T) {
+	dir := t.TempDir()
+	defaultJSON := `{"collections":[{"database":"db","collection":"default_col","fields":{}}]}`
+	customJSON := `{"collections":[{"database":"db","collection":"custom_col","fields":{}}]}`
+
+	if err := os.WriteFile(filepath.Join(dir, "default.json"), []byte(defaultJSON), 0o644); err != nil {
+		t.Fatalf("write default: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "custom.json"), []byte(customJSON), 0o644); err != nil {
+		t.Fatalf("write custom: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "ignore.txt"), []byte("x"), 0o644); err != nil {
+		t.Fatalf("write ignore: %v", err)
+	}
+
+	defaultOnly, err := LoadCollections(dir, true)
+	if err != nil {
+		t.Fatalf("LoadCollections(default) error = %v", err)
+	}
+	if len(defaultOnly.Collections) != 1 || defaultOnly.Collections[0].Name != "default_col" {
+		t.Fatalf("expected only default collection, got %+v", defaultOnly.Collections)
+	}
+
+	nonDefault, err := LoadCollections(dir, false)
+	if err != nil {
+		t.Fatalf("LoadCollections(non-default) error = %v", err)
+	}
+	if len(nonDefault.Collections) != 1 || nonDefault.Collections[0].Name != "custom_col" {
+		t.Fatalf("expected only custom collection, got %+v", nonDefault.Collections)
+	}
+}
+
+func TestLoadCollectionsMissingPathFallsBackToEmbeddedDefault(t *testing.T) {
+	cfg, err := LoadCollections(filepath.Join(t.TempDir(), "does-not-exist"), true)
+	if err != nil {
+		t.Fatalf("LoadCollections() error = %v", err)
+	}
+	if len(cfg.Collections) == 0 {
+		t.Fatalf("expected embedded default collections")
+	}
+}
+
+func TestLoadCollectionsValidationErrorForMissingNames(t *testing.T) {
+	file := filepath.Join(t.TempDir(), "bad.json")
+	bad := `{"collections":[{"database":"","collection":"","fields":{}}]}`
+	if err := os.WriteFile(file, []byte(bad), 0o644); err != nil {
+		t.Fatalf("write bad file: %v", err)
+	}
+
+	_, err := LoadCollections(file, false)
+	if err == nil {
+		t.Fatalf("expected validation error for empty names")
+	}
+}