Assisted Service Writing Unit Tests

Writing Unit Tests in Assisted-Service

Overview

Unit tests in assisted-service use Ginkgo/Gomega BDD framework with gomock for mocking. Core principle: Every gomock controller MUST call ctrl.Finish() in AfterEach to verify mock expectations.

Without ctrl.Finish(), tests pass even when mocks aren't called correctly - silent failures that hide bugs. Tests run against real PostgreSQL (suite or per-test) with automatic cleanup.

Quick Reference

| Scenario | Pattern |

|----------|---------|

| Testing with mocks | Create controller in BeforeEach, call ctrl.Finish() in AfterEach |

| Testing without mocks | Use It() blocks directly or table-driven tests |

| Database per test | PrepareTestDB() in BeforeEach, DeleteTestDB() in AfterEach |

| Database for suite | InitializeDBTest() in BeforeSuite, TerminateDBTest() in AfterSuite |

| Event verification | eventstest.NewEventMatcher with matchers |

| OCP version in tests | Use hardcoded strings or common.TestDefaultConfig — do not use TestVersion() |

When to Use Patterns

digraph mock_decision {
    "Testing interface deps?" [shape=diamond];
    "Need verify calls or control returns?" [shape=diamond];
    "Use gomock mocks" [shape=box];
    "Use real implementation" [shape=box];

    "Testing interface deps?" -> "Need verify calls or control returns?" [label="yes"];
    "Testing interface deps?" -> "Use real implementation" [label="no"];
    "Need verify calls or control returns?" -> "Use gomock mocks" [label="yes"];
    "Need verify calls or control returns?" -> "Use real implementation" [label="no"];
}

digraph db_decision {
    "Tests share data?" [shape=diamond];
    "Tests modify DB state?" [shape=diamond];
    "Suite-level DB" [shape=box];
    "Per-test DB" [shape=box];

    "Tests share data?" -> "Suite-level DB" [label="yes"];
    "Tests share data?" -> "Tests modify DB state?" [label="no"];
    "Tests modify DB state?" -> "Per-test DB" [label="yes"];
    "Tests modify DB state?" -> "Suite-level DB" [label="no"];
}

Scope

Covers: Non-subsystem tests in internal/ and pkg/ with gomock, Ginkgo/Gomega, database, events.

Does NOT cover: Subsystem tests (subsystem/), E2E, external service integration, performance tests. Subsystem tests use different patterns, including common.TestVersion() for OCP versions.

Test files: *_test.go (same package). Suites: *_suite_test.go.

Critical: Gomock Controllers MUST Call Finish()

Every Describe/Context creating a gomock controller needs ctrl.Finish() in AfterEach. No exceptions.

Without ctrl.Finish():

• .Times(N) - Expected call count NOT checked
• .MaxTimes(0) - Unexpected calls NOT caught
• .Do() / .DoAndReturn() - Mock behavior runs without verification

BeforeEach(func() {
    ctrl = gomock.NewController(GinkgoT())
    mockHandler = eventsapi.NewMockHandler(ctrl)
})

AfterEach(func() {
    ctrl.Finish()  // REQUIRED - verifies all EXPECT() constraints
})

Why this matters: Missing ctrl.Finish() causes silent test failures - tests pass even when mocks aren't called correctly. Real bugs found in commit 338133e05 MGMT-23548.

Letter = Spirit: Following the pattern exactly IS following the spirit. This isn't ritual - it's how gomock verification works.

Database Setup Patterns

Suite-level (shared DB, read-only tests):

BeforeSuite(func() { common.InitializeDBTest() })
AfterSuite(func() { common.TerminateDBTest() })

Per-test (isolated DB, tests modify state):

BeforeEach(func() { db, dbName = common.PrepareTestDB() })
AfterEach(func() { common.DeleteTestDB(db, dbName) })

Event Testing

Use eventstest.NewEventMatcher with specific matchers:

mockEvents.EXPECT().SendHostEvent(gomock.Any(), eventstest.NewEventMatcher(
    eventstest.WithNameMatcher(eventgen.HostStatusUpdatedEventName),
    eventstest.WithHostIdMatcher(host.ID.String())))

Matchers: WithNameMatcher, WithHostIdMatcher, WithClusterIdMatcher, WithInfraEnvIdMatcher, WithSeverityMatcher

Table-Driven Tests

DescribeTable (simple cases):

DescribeTable("FunctionName",
    func(input string, valid bool) { /* test logic */ },
    Entry("descriptive case 1", "value1", true),
    Entry("descriptive case 2", "value2", false))

Struct array (complex scenarios):

tests := []struct{name, input string; valid bool}{
    {name: "case 1", input: "val1", valid: true}}
for _, t := range tests { It(t.name, func() { /* ... */ }) }

Test Structure

Ginkgo hierarchy: Describe("Component") → Context("when X") → It("should Y")

Isolation: No shared state between It blocks. Use BeforeEach for setup.

Gomock matchers: .Times(N), .MaxTimes(0), .AnyTimes(), gomock.Any()

OCP Versions: Use Hardcoded Strings, Not TestVersion()

Do not use common.TestVersion() in non-subsystem tests. TestVersion() resolves versions dynamically from data files and is designed for subsystem tests (subsystem/), which run against the real service. Non-subsystem tests mock version data and should use hardcoded version strings directly.

Correct patterns:

OpenshiftVersion: swag.String("4.14"),

Or use the package-level defaults from internal/common/test_configuration.go:

OpenshiftVersion: swag.String(common.OpenShiftVersion),
ReleaseVersion:   common.ReleaseVersion,
ReleaseImageUrl:  common.ReleaseImageURL,

See docs/dev/test-versions.md for the TestVersion() API used in subsystem tests.

Red Flags - Stop and Fix

These thoughts mean STOP - fix the issue:

• "Tests are passing, mocks must be working" → Add ctrl.Finish() in AfterEach
• "Too complex to set up properly" → Follow patterns, don't skip structure
• "Minimum viable test to satisfy review" → Tests must verify behavior, not theater
• "I'll add cleanup/verification later" → Do it now, tests will merge broken
• Code has gomock.NewController but no ctrl.Finish() → Silent failures
• Using common.TestVersion() outside subsystem/ → Wrong pattern; use hardcoded strings or common.TestDefaultConfig

If you're rationalizing shortcuts due to time pressure, the test will be broken. No exceptions.

Common Mistakes

| Mistake | Symptom | Fix |

|---------|---------|-----|

| Missing ctrl.Finish() | Tests pass when mocks not called | Add ctrl.Finish() in AfterEach |

| Shared variables between tests | Flaky tests, race conditions | Move initialization to BeforeEach |

| Missing GinkgoT() | Controller doesn't report failures | Use gomock.NewController(GinkgoT()) |

| Generic Entry names | "test 1", "test 2" in output | Descriptive: "valid IPv4 CIDR" |

| Wrong DB pattern | Pollution between tests | Suite-level for reads, per-test for writes |

| No event matchers | Generic gomock.Any() for events | Use eventstest.NewEventMatcher with specific matchers |

| Using TestVersion() | Wrong abstraction for non-subsystem tests | Use hardcoded strings or common.TestDefaultConfig |

Before Submitting

Check every test file:

• [ ] Every gomock.NewController has ctrl.Finish() in AfterEach
• [ ] No shared state (all setup in BeforeEach)
• [ ] Descriptive names ("valid IPv4 CIDR" not "test 1")
• [ ] Database cleanup if using PrepareTestDB()
• [ ] No TestVersion() usage — use hardcoded strings or common.TestDefaultConfig
• [ ] Tests pass: go test -v ./path/to/package

Red flags: Missing ctrl.Finish() → silent failures. Shared variables → flaky tests.