ARCExpect API design

The main goal of ARCExpect is providing an API surface that creates the common validatiopn cases without the need for much custom input. The following principles guide the design of the API:

• Semantic: Creating a validation case should be as easy as expressing it in words. Therefore, the API should be as close as possible to the natural language.
• Simple: The API should be simple to use and understand. It should not require a lot of boilerplate code to create a validation case.
• Customizable: As is always the case, there are exceptions to the rule where the API should be flexible enough to allow for custom validation cases.

API Design

Semantic Methods for validation case creation in the Validate namespace

Methods in the Validate (sub)namespace(s) should mirror an english sentence in the imperative mood of the following form, where words in brackets () are left out for brevity and/or are optional, and words in angle brackets <> are placeholders for the actual values:

Validate.(for <article>)<object>(that)<predicate>(is true)

examples:

• Validate.Param.ValueIsEqualTo(expectedValue) method represents:

  Validate (for a) param(eter that it's) value is equal to (the) value <expected value>

• Validate.ParamCollection.ContainsParamWithTerm(expectedTerm) method represents:

  Validate (for a) param(eter) collection (that it) contains (a) parameter with (the) term <expected term>

Objects

As validation cases are fundamentally built for validating ControlledVocabulary Tokens (CvParams / IParams), this reflected in the objects of the 'sentences' provided as methods of the API.

The following objects should be supported:

• Param represents a single object implementing the IParam interface.
• ParamCollection represents a collection of IParams.

Predicates

Predicates are the conditions that the object(s) should satisfy. Generic methods should be provided to cover predicates that are not directly provided by the API to satisfy the Customizable principle. The following predicates should be supported out of the box:

Object	Predicate	Signature	Description
IParam (Param)	SatisfiesPredicate	(IParam -> bool) -> IParam -> unit	generic method to validate wether a single IParam satisfies any kind of predicate (predicate here refers to a function that projects IParam -> bool)
IParam (Param)	IsEqualTo	IParam -> IParam -> unit	validates wether the given param is exactly equal (structural equality regarding all object fields) to the expected param
IParam (Param)	ValueIsEqualTo	ParamValue -> IParam -> unit	validates wether the given param's value is equal to the expected ParamValue.
IParam (Param)	TermIsEqualTo	CvTerm -> IParam -> unit	validates wether the given param's term is equal to the expected CvTerm
seq<#IParam> (ParamCollection)	SatisfiesPredicate	(seq<#IParam> -> bool) -> seq<#IParam> -> unit	generic method to validate wether a collection of IParams satisfies any kind of predicate (predicate here refers to a function that projects the whole sequence seq<#IParam> -> bool)
seq<#IParam> (ParamCollection)	IsNotEmpty	seq<#IParam> -> unit	validates that the given collection of IParams is not empty (has a length > 0)
seq<#IParam> (ParamCollection)	HasLength	int -> seq<#IParam> -> unit	validates wether the given collection of IParams has as many items as expected
seq<#IParam> (ParamCollection)	AllItemsSatisfyPredicate	(IParam> -> bool) -> seq<#IParam> -> unit	generic method to validate wether all items in a collection of IParams satisfy any kind of predicate (predicate here refers to a function that projects one item at a time IParam -> bool)
seq<#IParam> (ParamCollection)	AtLeastOneItemSatisfiesPredicate	(IParam> -> bool) -> seq<#IParam> -> unit	generic method to validate wether at least one item in a collection of IParams satisfies any kind of predicate (predicate here refers to a function that projects one item at a time IParam -> bool)
seq<#IParam> (ParamCollection)	ContainsItem	IParam -> seq<#IParam> -> unit	validates wether the given collection of IParams contains the expected IParam (by structural equality regarding all object fields)
seq<#IParam> (ParamCollection)	ContainsItemWithValue	ParamValue -> seq<#IParam> -> unit	validates wether the given collection of IParams contains an item with the expected ParamValue
seq<#IParam> (ParamCollection)	ContainsItemWithTerm	CvTerm -> seq<#IParam> -> unit	validates wether the given collection of IParams contains an item with the expected CvTerm