module

Assert

Annotation based object validation library.

See the Assert::Assertions namespace for the full assertion list as well as each assertion class for more detailed information/examples.

See Assert::Assertions::Assertion for common/high level assertion usage documentation.

Example Usage

Assert supports both object based validations via annotations as well as ad hoc value validations via class methods.

Object Validation

require "assert"

class User
  include Assert

  def initialize(@name : String, @age : Int32?, @email : String, @password : String); end

  # Assert their name is not blank
  @[Assert::NotBlank]
  property name : String

  # Asserts that their age is >= 0 AND not nil
  @[Assert::NotNil]
  @[Assert::GreaterThanOrEqual(value: 0)]
  property age : Int32?

  # Assert their email is not blank AND is a valid format
  @[Assert::Email(message: "'%{actual}' is not a proper email")]
  @[Assert::NotBlank]
  property email : String

  # Assert their password is between 7 and 25 characters
  @[Assert::Size(Range(Int32, Int32), range: 7..25)]
  property password : String
end

user = User.new "Jim", 19, "test@email.com", "monkey123"

# #valid? returns `true` if `self` is valid, otherwise `false`
user.valid? # => true

user.email = "foobar"
user.password = "hi"

# #valid? returns `true` if `self` is valid, otherwise `false`
user.valid? # => false

# #validate returns an array of assertions that were not valid
user.validate.empty? # => false

begin
  # #validate! raises an exception if `self` is not valid
  user.validate!
rescue ex : Assert::Exceptions::ValidationError
  ex.to_s    # => Validation tests failed:  'foobar' is not a proper email, 'password' is too short.  It should have 7 character(s) or more
  ex.to_json # => {"code":400,"message":"Validation tests failed","errors":["'foobar' is not a proper email","'password' is too short.  It should have 7 character(s) or more"]}
end

Ad Hoc Validation

# Each assertion automatically defines a shortcut class method for ad hoc validations.
Assert.not_blank "foo" # => true
Assert.not_blank ""    # => false

begin
  # The bang version will raise if the value is invalid.
  Assert.not_blank! "   "
rescue ex
  ex.to_s # => Validation tests failed: 'actual' should not be blank
end

begin
  # Optional arguments can be used just like the annotation versions.
  Assert.equal_to! 15, 20, message: "%{actual} does not equal %{value}"
rescue ex
  ex.to_s # => Validation tests failed: 15 does not equal 20
end

Class methods

choice(actual : PropertyType, choices : ChoicesType, min_matches : Int32 | Nil = nil, max_matches : Int32 | Nil = nil, min_message : String | Nil = nil, max_message : String | Nil = nil, multiple_message : String | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType, ChoicesType

Assert::Assertions::Choice assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

choice!(actual : PropertyType, choices : ChoicesType, min_matches : Int32 | Nil = nil, max_matches : Int32 | Nil = nil, min_message : String | Nil = nil, max_message : String | Nil = nil, multiple_message : String | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType, ChoicesType

Assert::Assertions::Choice assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

divisible_by(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::DivisibleBy assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

divisible_by!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::DivisibleBy assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

email(actual : Union(String, Nil), mode : EmailValidationMode = EmailValidationMode::Loose, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Email assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

email!(actual : Union(String, Nil), mode : EmailValidationMode = EmailValidationMode::Loose, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Email assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

equal_to(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::EqualTo assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

equal_to!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::EqualTo assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

greater_than(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::GreaterThan assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

greater_than!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::GreaterThan assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

greater_than_or_equal(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::GreaterThanOrEqual assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

greater_than_or_equal!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::GreaterThanOrEqual assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

in_range(actual : PropertyType, range : RangeType, not_in_range_message : String | Nil = nil, min_message : String | Nil = nil, max_message : String | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType, RangeType

Assert::Assertions::InRange assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

in_range!(actual : PropertyType, range : RangeType, not_in_range_message : String | Nil = nil, min_message : String | Nil = nil, max_message : String | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType, RangeType

Assert::Assertions::InRange assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

ip(actual : Union(String, Nil), version : IPVersion = IPVersion::IPV4, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Ip assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

ip!(actual : Union(String, Nil), version : IPVersion = IPVersion::IPV4, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Ip assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

is_blank(actual : Union(String, Nil), normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsBlank assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

is_blank!(actual : Union(String, Nil), normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsBlank assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

is_false(actual : Union(Bool, Nil), message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsFalse assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

is_false!(actual : Union(Bool, Nil), message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsFalse assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

is_nil(actual : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsNil assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

is_nil!(actual : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsNil assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

is_true(actual : Union(Bool, Nil), message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsTrue assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

is_true!(actual : Union(Bool, Nil), message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::IsTrue assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

less_than(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::LessThan assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

less_than!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::LessThan assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

less_than_or_equal(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::LessThanOrEqual assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

less_than_or_equal!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::LessThanOrEqual assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

not_blank(actual : Union(String, Nil), normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::NotBlank assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

not_blank!(actual : Union(String, Nil), normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::NotBlank assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

not_equal_to(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::NotEqualTo assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

not_equal_to!(actual : PropertyType, value : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::NotEqualTo assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

not_nil(actual : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::NotNil assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

not_nil!(actual : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::NotNil assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

regex_match(actual : Union(String, Nil), pattern : Regex, match : Bool = true, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::RegexMatch assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

regex_match!(actual : Union(String, Nil), pattern : Regex, match : Bool = true, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::RegexMatch assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

size(actual : PropertyType, range : RangeType, normalizer : Proc(PropertyType, PropertyType) | Nil = nil, exact_message : String | Nil = nil, min_message : String | Nil = nil, max_message : String | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType, RangeType

Assert::Assertions::Size assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

size!(actual : PropertyType, range : RangeType, normalizer : Proc(PropertyType, PropertyType) | Nil = nil, exact_message : String | Nil = nil, min_message : String | Nil = nil, max_message : String | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType, RangeType

Assert::Assertions::Size assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

url(actual : Union(String, Nil), protocols : Array(String) = ["http", "https"] of ::String, relative_protocol : Bool = false, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Url assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

url!(actual : Union(String, Nil), protocols : Array(String) = ["http", "https"] of ::String, relative_protocol : Bool = false, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Url assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

uuid(actual : Union(String, Nil), versions : Array(UUID::Version) = [UUID::Version::V1, UUID::Version::V2, UUID::Version::V3, UUID::Version::V4, UUID::Version::V5], variants : Array(UUID::Variant) = [UUID::Variant::RFC4122], strict : Bool = true, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Uuid assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

uuid!(actual : Union(String, Nil), versions : Array(UUID::Version) = [UUID::Version::V1, UUID::Version::V2, UUID::Version::V3, UUID::Version::V4, UUID::Version::V5], variants : Array(UUID::Variant) = [UUID::Variant::RFC4122], strict : Bool = true, normalizer : Proc(String, String) | Nil = nil, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Uuid assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

valid(actual : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Valid assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible.

valid!(actual : PropertyType, message : String | Nil = nil, groups : Array(String) | Nil = nil) : Bool forall PropertyType

Assert::Assertions::Valid assertion shortcut method.

Can be used for ad hoc validations when applying annotations is not possible. Raises an Assert::Exceptions::ValidationError if the value is not valid.

Instance methods

valid?(groups : Array(String) = Array(String).new) : Bool

Returns true if self is valid, otherwise false. Optionally only run assertions a part of the provided groups.

valid?(*groups : String) : Bool

Returns true if self is valid, otherwise false. Optionally only run assertions a part of the provided groups.

validate(groups : Array(String) = Array(String).new) : Array(Assert::Assertions::Assertion)

Runs the assertions on self, returning the assertions that are not valid. Optionally only run assertions a part of the provided groups.

validate(*groups : String) : Array(Assert::Assertions::Assertion)

Runs the assertions on self, returning the assertions that are not valid. Optionally only run assertions a part of the provided groups.

validate!(groups : Array(String) = Array(String).new) : Nil

Runs the assertions on self, raises an Assert::Exceptions::ValidationError if self is not valid.

Optionally only run assertions a part of the provided groups.

validate!(*groups : String) : Nil

Runs the assertions on self, raises an Assert::Exceptions::ValidationError if self is not valid.

Optionally only run assertions a part of the provided groups.

Nested types