Cvoya.Graph.CompatibilityTests 1.0.0

Downloadable open-source computer software from CVOYA. See the CVOYA software catalog.

Cvoya.Graph.CompatibilityTests

A shippable compatibility test suite (TCK) for CVOYA graph providers. Implement one small SPI, bind the suite's I*Tests interfaces to your provider, and run the same 500+ contract test cases every in-tree provider runs - proving your provider actually behaves the way CVOYA graph promises.

🚀 Quick Start

dotnet add package Cvoya.Graph.CompatibilityTests

// 1. Implement the harness SPI against your provider.
public sealed class MyProviderHarness : IGraphProviderTestHarness
{
    public string ProviderName => "MyCompany.CVOYA graph.MyProvider";
    public CapabilitySet Capabilities => CapabilitySet.Of(
        GraphCapability.Transactions,
        GraphCapability.ComplexPropertyCascade); // list only verified features
    public ValueTask InitializeAsync() => /* start/connect infrastructure once per test class */;
    public ValueTask DisposeAsync() => /* release it */;
    public ValueTask<IGraph> GetGraphAsync(StoreIsolation isolation, CancellationToken ct) =>
        /* return an IGraph over an empty store */;
    public ValueTask SeedExternalGraphAsync(IGraph graph, string marker, CancellationToken ct) =>
        /* seed ContractExternalNode/Relationship through the provider-native API */;
    public ValueTask<IReadOnlyCollection<string>> GetStoreArtifactsAsync(
        IGraph graph, CancellationToken ct) =>
        /* stable backend label/table/index/constraint/function inventory */;
    public ValueTask<int> CountNodesByPropertyAsync(
        IGraph graph, string label, string propertyName, IReadOnlyCollection<string> values,
        CancellationToken ct) =>
        /* provider-native count used only for complex-property orphan assertions */;
    public bool IsExpectedConcurrentUpdateException(Exception exception) =>
        /* true only for provider-specific retryable write-contention errors */;
}

// 2. Declare one intermediate base class.
public abstract class MyProviderTest(MyProviderHarness harness)
    : CompatibilityTest(harness), IClassFixture<MyProviderHarness>;

// 3. Bind each suite interface - one line per interface.
public class BasicTests(MyProviderHarness h) : MyProviderTest(h), IBasicTests;
public class QueryTests(MyProviderHarness h) : MyProviderTest(h), IQueryTests;
public class ProviderContractTests(MyProviderHarness h) : MyProviderTest(h), IProviderContractTests;
// ... and so on for the rest of the I*Tests interfaces.

Run with GRAPHMODEL_COMPLIANCE_STRICT=1 dotnet test --report-trx for the certifying, guard-armed run. See the Certifying a provider chapter for the full workflow, and examples/CompatibilityTests.SampleHarness for a compiling skeleton.

Strict mode enforces the capability-eligible execution floor; it does not convert infrastructure failures into skips. GraphProviderUnavailableException always fails the test run. The harness owns stores and provider resources, while CompatibilityTest disposes a returned graph only when the graph itself implements IAsyncDisposable or IDisposable.

📦 What's in the package

• Harness SPI - IGraphProviderTestHarness, StoreIsolation, GraphProviderUnavailableException
• CompatibilityTest - the shared base class that runs the capability-skip/acquire/dispose choreography once; infrastructure failures always fail
• RequiresCapabilityAttribute - marks tests/interfaces that need an optional GraphCapability
• ComplianceGuard / ComplianceInventory - the method-identity guard (GRAPHMODEL_COMPLIANCE_STRICT=1) that requires every capability-eligible contract method, rejects provider replacements of packaged default test bodies, and lists any missing bindings; repeated theory rows do not increase coverage
• The I*Tests interfaces themselves - the actual contract, as default-implemented xUnit test methods

🔧 Capabilities

Some suite areas are optional (for example FullTextSearch). Declare only what your backing store actually supports via CapabilitySet.Of(...); the suite skips - never fails - tests that need an undeclared capability, with a fixed, parseable skip reason. The in-memory reference provider declares full-text search and executes those contracts with its index-free, case-insensitive whole-token matcher.

📚 Documentation

🌐 Complete Documentation

🔗 Related Packages

• Cvoya.Graph - Core graph abstractions
• Cvoya.Graph.Neo4j - Neo4j database provider (the suite's in-tree reference implementation)
• Cvoya.Graph.Serialization - Object serialization framework

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.