Conformance harness¶

forgetest.RunProviderConformance asserts the half of the provider contract the compiler cannot see: which sentinel to return, that a nil result and a nil error never come back together, that a size bound you accepted is actually enforced.

import forgetest "gitlab.com/phpboyscout/go/forge/test"

func TestConformance(t *testing.T) {
    forgetest.RunProviderConformance(t, forgetest.ConformanceConfig{
        NewProvider: func() forge.Provider { return newTestProvider(t) },
        Capabilities: forgetest.Capabilities{
            GetReleaseByTag: true,
            ListReleases:    false, // platform has no listing
        },
        Owner: "acme", Repo: "tool", Tag: "v1.0.0",
    })
}

For the narrative version (why it exists, what to do about each finding) see author a provider. This page is the field list.

What the harness runs¶

Seventeen checks, in this order. Each is wrapped so a panic from the provider is reported as a violation rather than ending the test run. The first provider to panic would otherwise take every later check down with it.

Capabilities: declare honestly¶

The harness checks both directions: an undeclared capability must return ErrNotSupported, and a declared one must not. Over-declaring is caught because it would otherwise skip every check for that method while implying they ran.

Most providers declare Sites: false, and that is the capability pattern working rather than a gap: two of the four first-party forges have no site feature at all.

ConformanceConfig: required, optional, and what a blank field costs¶

An omitted optional field means the corresponding check is skipped, not assumed satisfied. That is deliberate, because a guessed fixture produces a verdict nobody can trust. It does mean a sparse config runs a much weaker suite than it looks like it is running.

Four of those are worth supplying even though nothing forces you to.

UnknownVisibilityPath names a repository your fixture reports without a privacy field, so the harness can prove the provider decodes fail-closed rather than letting an absent field become false and therefore public. Providers whose SDK models privacy as a plain bool are exactly the ones that need it.

EchoesCreatedBody declares that your fixture returns the body it was sent rather than a canned one. The sanitisation checks compare what came back against what went in, so a canned body would make the redaction check pass without redacting anything.

NewProviderWithLogger is the only way the harness can inject a logger, because NewProvider hands back an already-built provider. Without it, the rule that a provider never logs at ERROR for a condition it also returns goes unchecked.

NewProviderAt builds your provider against a URL the harness supplies, rather than against your fixture:

NewProviderAt: func(baseURL string) forge.Provider {
    return newProviderAt(baseURL, nil)
},

It exists because three of the refusals cannot be provoked from a fixture. Nothing makes a healthy forge rate-limit a test, so the harness stands up its own server, answers with one status and set of headers, and checks what your provider made of it. If your NewProvider already closes over a server URL, supplying this is usually a two-line refactor.

Without it the refusal mapping is unverified rather than assumed satisfied, which is the whole point: an unsentinelled refusal is the defect this check exists for, and it is invisible until a caller needs to branch on it.

Capturing logs in your own tests¶

forgetest.CaptureLogger returns a logger and a function yielding the records it collected. It wraps exactly as forge.NormaliseLogger does, so what you assert on is what a consumer would see, redaction included.

Related¶

• Author a provider: the contract these checks enforce
• Test against a forge: forgetest.Source and the published mocks
• Errors: the sentinels the harness insists on