Skip to content

Validate an implementation

altar.testing publishes the same behavioral contracts used for Altar's reference implementations. Persistence contracts use the exported ContractModelPlugin, a synthetic result model spanning scalar and named-detail schemas. Backend conformance therefore depends only on Altar's storage semantics, never on a ChromBPNet-shaped schema, reducer, fold count, runtime, or biological policy.

Available contracts

  • PluginDiscoveryContract
  • ModelResultContract (ModelPluginContract is its compatibility name)
  • InlineScorerContract
  • ContainerScorerContract
  • ExecutionBackendContract
  • ScoreStoreContract
  • DetailStoreContract
  • AnnotationSourceContract
  • SqlAnnotationSourceContract
  • WritableAnnotationSourceContract (opt-in, for annotation sources that are written to)
  • VariantGeneLinkSourceContract
  • VariantGeneLinkStoreContract
  • StorageContract
  • JobQueueContract (provisional)
  • AuthProviderContract (provisional)

The two provisional suites, and the InMemoryJobQueue test double, follow their provisional contracts and may change in a minor release.

Use a contract

import pytest
from altar.testing import AnnotationSourceContract


class TestMySource(AnnotationSourceContract):
    @pytest.fixture
    def source(self):
        return MySource(FakeBackend())

Read the selected contract's fixture requirements and supply only those fixtures. An annotation source that implements a published AnnotationContract also returns it from the contract fixture, and the suite checks the source against it with assert_implements_contract. An annotation source that is also written to, such as a cache of annotations computed by a host pipeline, additionally subclasses WritableAnnotationSourceContract. It checks that writes are stored under the source's identity, that a source with another identity sees none of them as annotated, and that reads never mix identities. Keep these tests in the extension package so compatibility is checked against every supported Altar version.

ContractModelPlugin and contract_model_identity() are available when an adapter-specific test needs the same neutral schema or a complete deterministic run identity. Model bindings should instead test their real plugin directly with ModelResultContract and the matching compute-capability contract.

Model bindings should compose the contracts for the capabilities they actually provide: discovery plus the result/schema contract, and then either the inline-scorer or container-plan contract. Annotation sources, variant–gene link sources, execution backends, and stores use their own axis-specific contracts rather than a model-shaped umbrella suite.

Add integration-specific tests

Conformance proves shared behavior, not scientific correctness. Also test:

  • exact schemas, units, and field direction;
  • supported and rejected variants;
  • missing, zero, null, and duplicate records;
  • provenance and genome-build mismatches;
  • deterministic task commands and resource requests;
  • importability without optional SDKs, credentials, GPUs, or weights;
  • entry-point discovery in an installed environment.

An external binding should be type-checked against public façade imports and tested in an environment where the containing host application is not importable.