Class: SleepingKingStudios::Tools::Assertions

Parent Namespace

SleepingKingStudios::Tools

Inherited Classes

SleepingKingStudios::Tools::Base > Object

Defined In

lib/sleeping_king_studios/tools/assertions.rb

Table Of Contents

• Overview
• Direct Subclasses
• Defined Under Namespace
• Class Methods
  • instance
• Instance Methods
  • aggregator_class
  • assert
  • assert_blank
  • assert_boolean
  • assert_class
  • assert_group
  • assert_instance_of
  • assert_matches
  • assert_name
  • assert_nil
  • assert_not_nil
  • assert_presence
  • error_message_for
  • validate
  • validate_blank
  • validate_boolean
  • validate_class
  • validate_group
  • validate_instance_of
  • validate_matches
  • validate_name
  • validate_nil
  • validate_not_nil
  • validate_presence

Overview

Methods for asserting on the state of a function or application.

Back To Top

Direct Subclasses

SleepingKingStudios::Tools::Assertions::Aggregator

Back To Top

Defined Under Namespace

Classes

Aggregator, AssertionError

Back To Top

Class Methods

.instance => SleepingKingStudios::Tools::Base

Inherited From

SleepingKingStudios::Tools::Base

Returns

• (SleepingKingStudios::Tools::Base) — a memoized instance of the tools class.

Back To Top

Instance Methods

#aggregator_class => Class

Returns

• (Class) — the class used to aggregate grouped assertion failures.

#assert(error_class: AssertionError, message: nil, &block) => void

Asserts that the block returns a truthy value.

Examples

Assertions.assert { true == false }
#=> raises an AssertionError with message 'block returned a falsy value'

Assertions.assert { true == true }
#=> does not raise an exception

Parameters

• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.

Yields

• the block to evaluate.

Yield Returns

• (Object) — the returned value of the block.

Returns

• (void)

Raises

• (AssertionError) — if the block does not return a truthy value.

#assert_blank(value, as: 'value', error_class: AssertionError, message: nil) => void

Asserts that the value is either nil or empty.

Examples

Assertions.assert_blank(nil)
#=> does not raise an exception

Assertions.assert_blank(Object.new)
#=> raises an AssertionError with message 'value must be nil or empty'

Assertions.assert_blank([])
#=> does not raise an exception

Assertions.assert_blank([1, 2, 3])
#=> raises an AssertionError with message 'value must be nil or empty'

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.

Returns

• (void)

Raises

• (AssertionError) — if the value is not nil and either does not respond to #empty? or value.empty returns false.

#assert_boolean(value, as: 'value', error_class: AssertionError, message: nil, optional: false) => void

Asserts that the value is either true or false.

Examples

Assertions.assert_boolean(nil)
#=> raises an AssertionError with message 'value must be true or false'

Assertions.assert_boolean(Object.new)
#=> raises an AssertionError with message 'value must be true or false'

Assertions.assert_boolean(false)
#=> does not raise an exception

Assertions.assert_boolean(true)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (AssertionError) — if the value is not true or false.

#assert_class(value, as: 'value', error_class: AssertionError, message: nil, optional: false) => void

Asserts that the value is a Class.

Examples

Assertions.assert_class(Object.new)
#=> raises an AssertionError with message 'value is not a class'

Assertions.assert_class(String)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (AssertionError) — if the value is not a Class.

#assert_group(error_class: AssertionError, message: nil, &assertions) => void

Also known as: aggregate

Evaluates a series of assertions and combines all failures.

Examples

Assertions.assert_group do |group|
  group.assert_name(nil, as: 'label')
  group.assert_instance_of(0.0, expected: Integer, as: 'quantity')
end
# raises an AssertionError with message: "label can't be blank, quantity is not an instance of Integer"

Parameters

• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.

Yields

• the assertions to evaluate.

Yield Parameters

• aggregator (Aggregator) — the aggregator object.

Returns

• (void)

Raises

• (AssertionError) — if any of the assertions fail.

#assert_instance_of(value, expected:, as: 'value', error_class: AssertionError, message: nil, optional: false) => void

Asserts that the value is an example of the given Class.

Examples

Assertions.assert_instance_of(:foo, expected: String)
#=> raises an AssertionError with message 'value is not an instance of String'

Assertions.assert_instance_of('foo', expected: String)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• expected (Class) — the expected class.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the expected class is not a Class.
• (AssertionError) — if the value is not an instance of the expected class.

#assert_matches(value, expected:, as: 'value', error_class: AssertionError, message: nil, optional: false) => void

Asserts that the value matches the expected object using #===.

Examples

Assertions.assert_matches('bar', expected: /foo/)
#=> raises an AssertionError with message 'value does not match the pattern /foo/'

Assertions.assert_matches('foo', expected: /foo/)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• expected (#===) — the expected object.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (AssertionError) — if the value does not match the expected object.

#assert_name(value, as: 'value', error_class: AssertionError, message: nil, optional: false) => void

Asserts that the value is a non-empty String or Symbol.

Examples

Assertions.assert_name(nil)
#=> raises an AssertionError with message "value can't be blank"

Assertions.assert_name(Object.new)
#=> raises an AssertionError with message 'value is not a String or a Symbol'

Assertions.assert_name('')
#=> raises an AssertionError with message "value can't be blank"

Assertions.assert_name('foo')
#=> does not raise an exception

Assertions.assert_name(:bar)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (AssertionError) — if the value is not a String or a Symbol, or if the value is empty.

#assert_nil(value, as: 'value', error_class: AssertionError, message: nil) => void

Asserts that the value is nil.

Examples

Assertions.assert_nil(nil)
#=> does not raise an exception

Assertions.assert_nil(Object.new)
#=> raises an AssertionError with message 'value must be nil'

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.

Returns

• (void)

Raises

• (AssertionError) — if the value is not nil.

#assert_not_nil(value, as: 'value', error_class: AssertionError, message: nil) => void

Asserts that the value is not nil.

Examples

Assertions.assert_not_nil(nil)
#=> raises an AssertionError with message 'value must not be nil'

Assertions.assert_not_nil(Object.new)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.

Returns

• (void)

Raises

• (AssertionError) — if the value is nil.

#assert_presence(value, as: 'value', error_class: AssertionError, message: nil, optional: false) => void

Asserts that the value is not nil and not empty.

Examples

Assertions.assert_presence(nil)
#=> raises an AssertionError with message "can't be blank"

Assertions.assert_presence(Object.new)
#=> does not raise an exception

Assertions.assert_presence([])
#=> raises an AssertionError with message "can't be blank"

Assertions.assert_presence([1, 2, 3])
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• error_class (Class) — the exception class to raise on a failure.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (AssertionError) — if the value is nil, or if the value responds to #empty? and value.empty is true.

#error_message_for(scope, as: 'value', **options) => String

Generates an error message for a failed validation.

Examples

scope = 'sleeping_king_studios.tools.assertions.blank'

assertions.error_message_for(scope)
#=> 'value must be nil or empty'
assertions.error_message_for(scope, as: false)
#=> 'must be nil or empty'
assertions.error_message_for(scope, as: 'item')
#=> 'item must be nil or empty'

Parameters

• scope (String) — the message scope.
• options (Hash) — additional options for generating the message.

Options Hash (options)

• as (String) — the name of the validated property. Defaults to 'value'.
• expected (Object) — the expected object, if any.

Returns

• (String) — the generated error message.

#validate(message: nil, &block) => void

Asserts that the block returns a truthy value.

Examples

Assertions.validate { true == false }
#=> raises an ArgumentError with message 'block returned a falsy value'

Assertions.validate { true == true }
#=> does not raise an exception

Parameters

• message (String) — the exception message to raise on a failure.

Yields

• The block to evaluate.

Yield Returns

• (Object) — the returned value of the block.

Returns

• (void)

Raises

• (ArgumentError) — if the block does not return a truthy value.

#validate_blank(value, as: 'value', message: nil) => void

Asserts that the value is either nil or empty.

Examples

Assertions.validate_blank(nil)
#=> does not raise an exception

Assertions.validate_blank(Object.new)
#=> raises an ArgumentError with message 'value must be nil or empty'

Assertions.validate_blank([])
#=> does not raise an exception

Assertions.validate_blank([1, 2, 3])
#=> raises an ArgumentError with message 'value must be nil or empty'

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.

Returns

• (void)

Raises

• (ArgumentError) — if the value is not nil and either does not respond to #empty? or value.empty returns false.

#validate_boolean(value, as: 'value', message: nil, optional: false) => void

Asserts that the value is either true or false.

Examples

Assertions.validate_boolean(nil)
#=> raises an ArgumentError with message 'value must be true or false'

Assertions.validate_boolean(Object.new)
#=> raises an ArgumentError with message 'value must be true or false'

Assertions.validate_boolean(false)
#=> does not raise an exception

Assertions.validate_boolean(true)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the value is not true or false.

#validate_class(value, as: 'value', message: nil, optional: false) => void

Asserts that the value is a Class.

Examples

Assertions.validate_class(Object.new)
#=> raises an ArgumentError with message 'value is not a class'

Assertions.validate_class(String)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the value is not a Class.

#validate_group(message: nil, &validations) => void

Evaluates a series of validations and combines all failures.

Examples

Assertions.validate_group do |group|
  group.validate_name(nil, as: 'label')
  group.validate_instance_of(0.0, expected: Integer, as: 'quantity')
end
# raises an ArgumentError with message: "label can't be blank, quantity is not an instance of Integer"

Parameters

• message (String) — the exception message to raise on a failure.

Yields

• the validations to evaluate.

Yield Parameters

• aggregator (Aggregator) — the aggregator object.

Returns

• (void)

Raises

• (ArgumentError) — if any of the validations fail.

#validate_instance_of(value, expected:, as: 'value', message: nil, optional: false) => void

Asserts that the value is an example of the given Class.

Examples

Assertions.validate_instance_of(:foo, expected: String)
#=> raises an AssertionError with message 'value is not an instance of String'

Assertions.validate_instance_of('foo', expected: String)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• expected (Class) — the expected class.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the value is not an instance of the expected class.

#validate_matches(value, expected:, as: 'value', message: nil, optional: false) => void

Asserts that the value matches the expected object using #===.

Examples

Assertions.validate_matches('bar', expected: /foo/)
#=> raises an ArgumentError with message 'value does not match the pattern /foo/'

Assertions.validate_matches('foo', expected: /foo/)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• expected (#===) — the expected object.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the value does not match the expected object.

#validate_name(value, as: 'value', message: nil, optional: false) => void

Asserts that the value is a non-empty String or Symbol.

Examples

Assertions.validate_name(nil)
#=> raises an ArgumentError with message "value can't be blank"

Assertions.validate_name(Object.new)
#=> raises an AssertionError with message 'value is not a String or a Symbol'

Assertions.validate_name('')
#=> raises an ArgumentError with message "value can't be blank"

Assertions.validate_name('foo')
#=> does not raise an exception

Assertions.validate_name(:bar)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the value is not a String or a Symbol, or if the value is empty.

#validate_nil(value, as: 'value', message: nil) => void

Asserts that the value is nil.

Examples

Assertions.validate_nil(nil)
#=> does not raise an exception

Assertions.validate_nil(Object.new)
#=> raises an ArgumentError with message 'value must be nil'

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.

Returns

• (void)

Raises

• (ArgumentError) — if the value is not nil.

#validate_not_nil(value, as: 'value', message: nil) => void

Asserts that the value is not nil.

Examples

Assertions.validate_not_nil(nil)
#=> raises an ArgumentError with message 'value must not be nil'

Assertions.validate_not_nil(Object.new)
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.

Returns

• (void)

Raises

• (ArgumentError) — if the value is nil.

#validate_presence(value, as: 'value', message: nil, optional: false) => void

Asserts that the value is not nil and not empty.

Examples

Assertions.validate_presence(nil)
#=> raises an ArgumentError with message "can't be blank"

Assertions.validate_presence(Object.new)
#=> does not raise an exception

Assertions.validate_presence([])
#=> raises an ArgumentError with message "can't be blank"

Assertions.validate_presence([1, 2, 3])
#=> does not raise an exception

Parameters

• value (Object) — the value to assert on.
• as (String) — the name of the asserted value.
• message (String) — the exception message to raise on a failure.
• optional (true, false) — if true, allows nil values.

Returns

• (void)

Raises

• (ArgumentError) — if the value is nil, or if the value responds to #empty? and value.empty is true.

Back To Top

---

Back to Documentation | Versions | 1.2 | Reference | SleepingKingStudios | SleepingKingStudios::Tools