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, "[email protected]", "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

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

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

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

  Assert::Assertions::DivisibleBy assertion shortcut method.

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

  Assert::Assertions::DivisibleBy assertion shortcut method.

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

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

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

  Assert::Assertions::EqualTo assertion shortcut method.

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

  Assert::Assertions::EqualTo assertion shortcut method.

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

  Assert::Assertions::GreaterThan assertion shortcut method.

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

  Assert::Assertions::GreaterThan assertion shortcut method.

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

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

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

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

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

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

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

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

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

  Assert::Assertions::IsFalse assertion shortcut method.

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

  Assert::Assertions::IsFalse assertion shortcut method.

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

  Assert::Assertions::IsNil assertion shortcut method.

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

  Assert::Assertions::IsNil assertion shortcut method.

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

  Assert::Assertions::IsTrue assertion shortcut method.

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

  Assert::Assertions::IsTrue assertion shortcut method.

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

  Assert::Assertions::LessThan assertion shortcut method.

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

  Assert::Assertions::LessThan assertion shortcut method.

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

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

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

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

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

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

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

  Assert::Assertions::NotNil assertion shortcut method.

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

  Assert::Assertions::NotNil assertion shortcut method.

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

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

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

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

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

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

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

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

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

  Assert::Assertions::Valid assertion shortcut method.

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

  Assert::Assertions::Valid assertion shortcut method.

Instance Method Summary

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

  Returns true if self is valid, otherwise false.

• #valid?(*groups : String) : Bool

  Returns true if self is valid, otherwise false.

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

  Runs the assertions on self, returning the assertions that are not valid.

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

  Runs the assertions on self, returning the assertions that are not valid.

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

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

• #validate!(*groups : String) : Nil

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

Class Method Detail

Instance Method Detail