Entity References

With For constraints and column comparisons you can already relate entites with one another, but repeating these connections gets tedious. Entity references allow you to encapsulate these connections and also add some helper methods.

Example

For example if you have an assertion to check that all blog post authors actually exist

[Assertion]
public Constraint BlogPostAuthorsExist()
{
    return Check.For(Times.All, (Post post) =>
        Check.For(Times.AtLeastOnce, (Author author)
            => author.Id.IsEqualTo(post.AuthorId)));
}

then you can add an entity reference to the Post entity

public EntityReference<Author> Author => new(author => author.Id.IsEqualTo(AuthorId));

and can now simplify the assertion to be

[Assertion]
public Constraint BlogPostAuthorsExist()
{
    return Check.For(Times.All, (Post post) => post.Author.IsNotNull());
}

Warning

Entity references should only be used when you can be sure that exactly zero or one entities are going to match the connecting constraint. Otherwise the behaviour is undefined. In such cases you should use entity set references.

Note

The connecting constraints are not limited to simple comparisons as shown above, but support all constraints. More complex variants can be very helpful when certain requirements are often bundled together. Keep in mind that too complex constraints can have significant impact on assertion execution performance.

Use Cases

Asserting existance of entity matching the connecting constraint

Use IsNotNull or IsNull to check if an entity matching the connecting constraint exists or not.

Check.For(Times.All, (Post post) => post.Author.IsNotNull())
Check.For(Times.All, (Post post) => post.Author.IsNull())

Asserting equality with other entity (reference)

Entity references can be equality compared with entities or other entity references by using IsEqualTo and IsNotEqualTo. The same rules apply as if comparing two entities. When two entity references are compared and both do not exist, then they are considered equal.

Check.For(Times.All, (Author author) =>
    Check.For(Times.AtLeastOnce, (Post post) =>
        post.Author.IsEqualTo(author)))

Check.For(Times.All, (Author author) =>
    Check.For(Times.AtLeastOnce, (Post post) =>
        post.Author.IsNotEqualTo(author)))

Check.For(Times.All, (Post postA) => 
    Check.For(Times.AtLeastOnce, (Post postB) => 
        postA.Author.IsEqualTo(postB.Author)))

Check.For(Times.All, (Post postA) => 
    Check.For(Times.AtLeastOnce, (Post postB) => 
        postA.Author.IsNotEqualTo(postB.Author)))

Asserting property of referenced entity

Use Has to assert some property on the referenced entity. The constraint fails if the referenced entity does not exist.

Check.For(Times.All, (UserSession userSession) =>
    userSession.User.Has(user => user.EmailVerifiedAt.IsNotNull()))

Or assert on two referenced entities at once with

Check.For(Times.All, (AssertionSelection x) =>
    x.Definition.Has(x.Run, (definition, run) =>
        definition.OrganizationId.IsEqualTo(run.OrganizationId)))

which is equivalent to

Check.For(Times.All, (AssertionSelection x) =>
    x.Definition.Has(definition =>
        x.Run.Has(run =>
            definition.OrganizationId.IsEqualTo(run.OrganizationId))))