Overview  Namespace   Class 
SUMMARY: CHILDREN | PARAMETER | INSTPROC | INSTFILTER | INSTFORWARD DETAIL: | INSTPROC

::xounit
Class Assert

Heritage:
::xotcl::Object
Direct Known Subclasses:
::xounit::TestCase,
Associated Test:
::xounit::test::TestAssert
Class Assert
superclass ::xotcl::Object,
Assert is a library of assert methods.  Each
 assert methods checks some condition and simply
 returns if true, otherwise and error is thrown. 
 This error is an object reference.  Specifically
 a new AssertionError instance.  This allows messages
 to be carried along with the error and a common
 way to specific types of errors so that errors
 can be handled in the correct way. 

 Example:

 package require xounit
 namespace import -force ::xounit::*

 set a [ Assert new ]

 $a assert 1  "This will pass"
 $a assert 0  "This will fail"

 Asserts are simple procedures.  They replace
 two commads:

 if { ! $condition } {

     error $message
 }

 However the simplification of code is dramatic especially
 when checking many test variables. 

 Assert also works well with TestCase and TestRunner. It
 allows tests to be stopped at a point and a message can
 be returned to the TestCase to be analyzed and stored
 in a TestResult.
Variables
NameDefault ValueClassComment
 
Methods
NameComment
?assert {{prefix ""}}   Finds all assert methods on the current object
assert {condition {message ""}}   assert simply checks "condition" and throws a new AssertionError if false
assertClass {class {message ""}}   Checks object is a valid class
assertDoNotFindIn {tofind string {message ""}}   Try not to find a string, tofind, in another string, string
assertEquals {actual expected {message ""}}   Compares the values, actual and expected, and the assert fails if they ARE NOT equal and throws an AssertionError
assertEqualsTrim {actual expected {message ""}}   Compares the string trimmed values, actual and expected and the assert fails if they ARE NOT equal and throws an AssertionError
assertError {script {message ""}}   Asserts that a error will happend in script
assertExists {varName {message ""}}   Checks if varName exists on this object
assertExistsObject {varName {message ""}}   Asserts that the variable, varName, has a valid object handle as its value
assertExistsValue {varName {message ""}}   Asserts that a variable, varName, exists and has a non-empty value on the current object
assertFailure {script {message ""}}   Asserts that a failure will happend in script
assertFalse {condition {message ""}}   Checks for the negative condition and throws and error on the positive condition
assertFindIn {tofind string {message ""}}   Try to find a string, tofind, in another string, string
assertInfoExists {varName {message ""}}   Asserts that a variable, varName, exists and has a non-empty value on the current object
assertInteger {number {message ""}}   Asserts that number is an integer
assertIntegerInRange {number low high {message ""}}   Asserts that number is greater-than-or-equal-to low and less-than-or-equal-to high
assertListEquals {listA listB {message ""}}  
assertListLengthEquals {list length {message ""}}   Asserts that the length of list is equal to length
assertNoError {script {message ""}}   Asserts that no error will happend in script
assertNoFailure {script {message ""}}   Asserts that no failure will happend in script
assertNotEquals {actual expected {message ""}}   Compares expected and actual and throws an error if they ARE equal
assertNotEqualsTrim {actual expected {message ""}}   Compares the trimmed values expected and actual and throws an error if they ARE equal
assertNotExists {varName {message ""}}   Checks if varName does not exist on this object
assertObject {object {message ""}}   Checks object is a valid object
assertObjectInList {list object {message ""}}   Asserts that a list on the current object has object in that list
assertRegex {regex string {message ""}}   Try to match a pattern, regex, to a string, string
assertTrue {condition {message ""}}   Equivalent to assert
assertValue {value {message ""}}   Asserts that value has a non-empty value
assertValueInList {list value {message ""}}   Asserts that a list on the current object has value in that list
fail {message}   Throw an error with a message
   
Methods from ::xotcl::Object
#, ., ?, ?code, ?methods, ?object, abstract, copy, coverageFilter, defaultmethod, extractConfigureArg, filterappend, garbageCollect, get#, getClean#, hasclass, init, methodTag, mixinappend, move, profileFilter, self, setParameterDefaults, shell, tclcmd, traceFilter,
 
Instproc Detail

?assert

Description: 
 Finds all assert methods on the current object.
 This is useful in a debugger or xotclsh.  Can
 also be used with debug in TestCases.

 my debug [ my ?assert ]
Arguments:
Code: 
  ::xounit::Assert instproc ?assert {{prefix ""}}  {
   

        return [ my ?methods "assert$prefix" ]
    
}

assert

Description: 
 assert simply checks "condition" and throws
 a new AssertionError if false.  The AssertionError
 will contain the optional "message" string.

 condition - The condition to check for true ( 1 is true in Tcl )

 message A message to send on failure.
 
 set a [ ::xounit::Assert new ]

 $a assert 1  "This will pass"
 $a assert 0  "This will fail"

 #The failure will cause a Tcl error.
 #You should catch the error using a catch block and handle the error:

 if [ catch {

     $a assert 0 "Catch me"

 } result ] {

     puts [ $result message ]
 }

 #Assert failures throw an Exception. Use the message method
 #to get the message from the failure.
Arguments:
Code: 
  ::xounit::Assert instproc assert {condition {message ""}}  {
   

        if { $condition } {

            return 
            } else {

            error [ ::xounit::AssertionError new "$message" ]
        }
    
}

assertClass

Description: 
 Checks object is a valid class
Arguments:
Code: 
  ::xounit::Assert instproc assertClass {class {message ""}}  {
   

        my assertObject $class $message
        my assertTrue [ my isobject $class ] "$message\nExpected $class to be a class"
    
}

assertDoNotFindIn

Description: 
 Try not to find a string, tofind, in another string, string.
 If the string is found throw error.
Arguments:
Code: 
  ::xounit::Assert instproc assertDoNotFindIn {tofind string {message ""}}  {
   

        my assert [ expr [ string first $tofind $string ] == -1 ]  "$message\nExpected not to find $tofind in:\n$string"
    
}

assertEquals

Description: 
 Compares the values, actual and expected, and the assert fails
 if they ARE NOT equal and throws an AssertionError.

 actual - the first value to compare 
 expected - the second value to compare
 message - failure message
Arguments:
Code: 
  ::xounit::Assert instproc assertEquals {actual expected {message ""}}  {
   

        my assert [ expr { "$actual" == "$expected" } ]  "$message\nActual:   $actual\nExpected: $expected"
    
}

assertEqualsTrim

Description: 
 Compares the string trimmed values, actual and expected and the assert fails
 if they ARE NOT equal and throws an AssertionError.

 valueOne - the first value to compare 
 valueTwo - the second value to compare
 message - failure message
Arguments:
Code: 
  ::xounit::Assert instproc assertEqualsTrim {actual expected {message ""}}  {
   

        set actual [ string trim $actual ]
        set expected [ string trim $expected ]

        my assert [ expr { "$actual" == "$expected" } ]  "$message\nActual:   $actual\nExpected: $expected"
    
}

assertError

Description: 
 Asserts that a error will happend in script.
Arguments:
Code: 
  ::xounit::Assert instproc assertError {script {message ""}}  {
   

        my assert [ catch { uplevel [ self callinglevel ] $script } ]  "$message\nExpected to find an error in $script"
    
}

assertExists

Description: 
 Checks if varName exists on this object.
Arguments:
Code: 
  ::xounit::Assert instproc assertExists {varName {message ""}}  {
   

        my assertTrue [ my exists $varName ] "$message\nExpected $varName to exist"
    
}

assertExistsObject

Description: 
 Asserts that the variable, varName, has a valid
 object handle as its value.
Arguments:
Code: 
  ::xounit::Assert instproc assertExistsObject {varName {message ""}}  {
   

        my assertTrue [ my exists $varName ] "$message\nExpected $varName to exist"
        my assert [ Object isobject [ my set $varName ] ]  "$message\nExpected $varName to be an object"
    
}

assertExistsValue

Description: 
 Asserts that a variable, varName, exists and has a non-empty value on the current object.
Arguments:
Code: 
  ::xounit::Assert instproc assertExistsValue {varName {message ""}}  {
   

        my assertTrue [ my exists $varName ] "$message\nExpected $varName to exist"
        my assertNotEquals "" [ my set $varName ]  "$message\nExpected $varName to have a value"
    
}

assertFailure

Description: 
 Asserts that a failure will happend in script.
Arguments:
Code: 
  ::xounit::Assert instproc assertFailure {script {message ""}}  {
   

        my assert [ catch { uplevel [ self callinglevel ] $script } result ]  "$message\nExpected to find a failure in $script"

        my assert [ Object isobject $result ]  "$message\nExpected failure.  Error was found instead: $result"

        my assert [ $result hasclass ::xounit::AssertionError ]  "$message\nExpected to find a failure. Found object instead:\n$result is a [ $result info class ]"
    
}

assertFalse

Description: 
 Checks for the negative condition and throws
 and error on the positive condition.
Arguments:
Code: 
  ::xounit::Assert instproc assertFalse {condition {message ""}}  {
   

        if { $condition } { 

            error [ ::xounit::AssertionError new "$message" ]
        }
    
}

assertFindIn

Description: 
 Try to find a string, tofind, in another string, string.
 If the string is not found throw error.
Arguments:
Code: 
  ::xounit::Assert instproc assertFindIn {tofind string {message ""}}  {
   

        my assert [ expr [ string first $tofind $string ] != -1 ]  "$message\nExpected to find $tofind in:\n$string"
    
}

assertInfoExists

Description: 
 Asserts that a variable, varName, exists and has a non-empty value on the current object.
Arguments:
Code: 
  ::xounit::Assert instproc assertInfoExists {varName {message ""}}  {
   

        my assertTrue [ uplevel [ self callinglevel ] [ list info exists $varName ] ]  "$message\n Expected $varName to exist in [ self callingclass ]->[ self callingproc ]"
    
}

assertInteger

Description: 
 Asserts that number is an integer.
Arguments:
Code: 
  ::xounit::Assert instproc assertInteger {number {message ""}}  {
   

        my assertValue $number  "$message\nExpected input to be an integer, but was empty"

        if [ Object isobject $number ] {

        my assertFalse [ Object isobject $number ]  "$message\nExpected $number to be an integer, but found object [ $number info class]"

        }

        my assert [ string is integer $number ]  "$message\nExpected $number to be an integer"
    
}

assertIntegerInRange

Description: 
 Asserts that number is greater-than-or-equal-to low and
 less-than-or-equal-to high.
Arguments:
Code: 
  ::xounit::Assert instproc assertIntegerInRange {number low high {message ""}}  {
   

        my assertInteger $number $message

        my assert [ expr { $number >= $low } ]  "$message\nExpected $number to be at least than $low."

        my assert [ expr { $number <= $high } ]  "$message\nExpected $number to be no greater than $high."
    
}

assertListEquals

Description:
Arguments:
Code: 
  ::xounit::Assert instproc assertListEquals {listA listB {message ""}}  {
   


        for { set index 0 } { $index < [ llength $listA ] } { incr index } {

            my assertEquals [ lindex $listA $index ]  [ lindex $listB $index ]  "$message \n  Actual List: $listA \n  Expect List: $listB \n"

        }
    
}

assertListLengthEquals

Description: 
 Asserts that the length of list is equal to length. The 
 assert fails with message if the length of list is different than length.
Arguments:
Code: 
  ::xounit::Assert instproc assertListLengthEquals {list length {message ""}}  {
   

        my assertEquals [ llength $list ] $length  "Expected list length: $length\n Acutal list length: [ llength $list ]\n List: $list"
    
}

assertNoError

Description: 
 Asserts that no error will happend in script.
Arguments:
Code: 
  ::xounit::Assert instproc assertNoError {script {message ""}}  {
   

        set result ""

        my assertFalse [ catch { uplevel [ self callinglevel ] $script } result ]  "$message\nExpected not to find error in $script\n[ ::xoexception::Throwable extractMessage $result ]"
    
}

assertNoFailure

Description: 
 Asserts that no failure will happend in script.
Arguments:
Code: 
  ::xounit::Assert instproc assertNoFailure {script {message ""}}  {
   

        set result ""

        my assertFalse [ catch { uplevel [ self callinglevel ] $script } result ]  "$message\nExpected not to find a failure in $script\n[ ::xoexception::Throwable extractMessage $result ]"
    
}

assertNotEquals

Description: 
 Compares expected and actual and throws
 an error if they ARE equal.
Arguments:
Code: 
  ::xounit::Assert instproc assertNotEquals {actual expected {message ""}}  {
   

        my assert [ expr { "$actual" != "$expected" } ]  "$message\nActual: $actual\nNot Expected: $expected"
    
}

assertNotEqualsTrim

Description: 
 Compares the trimmed values expected and actual and throws
 an error if they ARE equal.
Arguments:
Code: 
  ::xounit::Assert instproc assertNotEqualsTrim {actual expected {message ""}}  {
   

        set actual [ string trim $actual ]
        set expected [ string trim $expected ]

        my assert [ expr { "$actual" != "$expected" } ]  "$message\nActual: $actual\nNot Expected: $expected"
    
}

assertNotExists

Description: 
 Checks if varName does not exist on this
 object.
Arguments:
Code: 
  ::xounit::Assert instproc assertNotExists {varName {message ""}}  {
   

        my assertFalse [ my exists $varName ] "$message\nExpected $varName to exist"
    
}

assertObject

Description: 
 Checks object is a valid object
Arguments:
Code: 
  ::xounit::Assert instproc assertObject {object {message ""}}  {
   

        my assertTrue [ my isobject $object ] "$message\nExpected $object to be an object"
    
}

assertObjectInList

Description: 
 Asserts that a list on the current object has object
 in that list.
Arguments:
Code: 
  ::xounit::Assert instproc assertObjectInList {list object {message ""}}  {
   

        my assertObject $object $message

        my assertNotEquals [ lsearch $list $object ] -1  "$message\nDid not find $object in list $list"
    
}

assertRegex

Description: 
 Try to match a pattern, regex, to a string, string.
 If the pattern does not match throw an error.
Arguments:
Code: 
  ::xounit::Assert instproc assertRegex {regex string {message ""}}  {
   

        my assertNotEquals  [ regexp $regex $string all ] 0   "$message\nExpected regex $regex to match string $string"

        if [ info exists all ] {

            return $all
        }

        return
    
}

assertTrue

Description: 
 Equivalent to assert. Use to be explicit about
 what you are testing.

 condition - The condition to check for true ( 1 is true in Tcl ).

 message - A message to send on failure.
Arguments:
Code: 
  ::xounit::Assert instproc assertTrue {condition {message ""}}  {
   

        uplevel [ self callinglevel ] [ list my assert $condition $message ]
    
}

assertValue

Description: 
 Asserts that value has a non-empty value.
Arguments:
Code: 
  ::xounit::Assert instproc assertValue {value {message ""}}  {
   

        my assertNotEquals "" $value  "$message\nExpected value to have a value"
    
}

assertValueInList

Description: 
 Asserts that a list on the current object has value
 in that list.
Arguments:
Code: 
  ::xounit::Assert instproc assertValueInList {list value {message ""}}  {
   

        my assertNotEquals [ lsearch $list $value ] -1  "$message\nDid not find $value in list $list"
    
}

fail

Description: 
 Throw an error with a message.  This is good
 for explicitly failing a testcase.
Arguments:
Code: 
  ::xounit::Assert instproc fail {message}  {
   

        error [ ::xounit::AssertionError new $message ]
    
}