module Assert

Overview

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

Defined in:

assert.cr
assertion.cr

Class Method Summary

Instance Method Summary

Class Method Detail

def self.choice(actual : PropertyType, choices : ChoicesType, min_matches : Int32? = nil, max_matches : Int32? = nil, min_message : String? = nil, max_message : String? = nil, multiple_message : String? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType, ChoicesType #

Assert::Assertions::Choice assertion shortcut method.

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


def self.choice!(actual : PropertyType, choices : ChoicesType, min_matches : Int32? = nil, max_matches : Int32? = nil, min_message : String? = nil, max_message : String? = nil, multiple_message : String? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.divisible_by(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::DivisibleBy assertion shortcut method.

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


def self.divisible_by!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.email(actual : Union(String, Nil), mode : EmailValidationMode = EmailValidationMode::Loose, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::Email assertion shortcut method.

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


def self.email!(actual : Union(String, Nil), mode : EmailValidationMode = EmailValidationMode::Loose, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.equal_to(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::EqualTo assertion shortcut method.

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


def self.equal_to!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.greater_than(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::GreaterThan assertion shortcut method.

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


def self.greater_than!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.greater_than_or_equal(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::GreaterThanOrEqual assertion shortcut method.

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


def self.greater_than_or_equal!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.in_range(actual : PropertyType, range : RangeType, not_in_range_message : String? = nil, min_message : String? = nil, max_message : String? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType, RangeType #

Assert::Assertions::InRange assertion shortcut method.

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


def self.in_range!(actual : PropertyType, range : RangeType, not_in_range_message : String? = nil, min_message : String? = nil, max_message : String? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.ip(actual : Union(String, Nil), version : IPVersion = IPVersion::IPV4, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::Ip assertion shortcut method.

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


def self.ip!(actual : Union(String, Nil), version : IPVersion = IPVersion::IPV4, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.is_blank(actual : Union(String, Nil), normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::IsBlank assertion shortcut method.

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


def self.is_blank!(actual : Union(String, Nil), normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.is_false(actual : Union(Bool, Nil), message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::IsFalse assertion shortcut method.

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


def self.is_false!(actual : Union(Bool, Nil), message : String? = nil, groups : Array(String)? = 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.


def self.is_nil(actual : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::IsNil assertion shortcut method.

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


def self.is_nil!(actual : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.is_true(actual : Union(Bool, Nil), message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::IsTrue assertion shortcut method.

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


def self.is_true!(actual : Union(Bool, Nil), message : String? = nil, groups : Array(String)? = 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.


def self.less_than(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::LessThan assertion shortcut method.

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


def self.less_than!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.less_than_or_equal(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::LessThanOrEqual assertion shortcut method.

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


def self.less_than_or_equal!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.not_blank(actual : Union(String, Nil), normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::NotBlank assertion shortcut method.

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


def self.not_blank!(actual : Union(String, Nil), normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.not_equal_to(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::NotEqualTo assertion shortcut method.

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


def self.not_equal_to!(actual : PropertyType, value : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.not_nil(actual : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::NotNil assertion shortcut method.

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


def self.not_nil!(actual : PropertyType, message : String? = nil, groups : Array(String)? = 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.


def self.regex_match(actual : Union(String, Nil), pattern : Regex, match : Bool = true, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::RegexMatch assertion shortcut method.

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


def self.regex_match!(actual : Union(String, Nil), pattern : Regex, match : Bool = true, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.size(actual : PropertyType, range : RangeType, normalizer : Proc(PropertyType, PropertyType)? = nil, exact_message : String? = nil, min_message : String? = nil, max_message : String? = nil, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType, RangeType #

Assert::Assertions::Size assertion shortcut method.

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


def self.size!(actual : PropertyType, range : RangeType, normalizer : Proc(PropertyType, PropertyType)? = nil, exact_message : String? = nil, min_message : String? = nil, max_message : String? = nil, message : String? = nil, groups : Array(String)? = 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.


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

Assert::Assertions::Url assertion shortcut method.

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


def self.url!(actual : Union(String, Nil), protocols : Array(String) = ["http", "https"] of ::String, relative_protocol : Bool = false, normalizer : Proc(String, String)? = nil, message : String? = nil, groups : Array(String)? = 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.


def self.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, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::Uuid assertion shortcut method.

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


def self.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, message : String? = nil, groups : Array(String)? = 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.


def self.valid(actual : PropertyType, message : String? = nil, groups : Array(String)? = nil) : Bool forall PropertyType #

Assert::Assertions::Valid assertion shortcut method.

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


def self.valid!(actual : PropertyType, message : String? = nil, groups : Array(String)? = 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 Method Detail

def 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.


[View source]
def valid?(*groups : String) : Bool #

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


[View source]
def 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.


[View source]
def 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.


[View source]
def 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.


[View source]
def 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.


[View source]