<commit_before>RFC 0199: Assertions
========================================================================
$Id$

@authors: friebe
@created: Tue Dec 22 20:15:04     2009
@status: draft
@target:  5.7.10
@category: unittest

Scope of Change
---------------
A new API for assertions will be added: <tt>Assert::that()</tt>.


Rationale
---------
More verbose error messages for the failure case.


Functionality
-------------
Instead of using the <tt>unittest.TestCase</tt> class' methods such as 
<tt>assertEquals()</tt> and friends the static <tt>Assert::that()</tt>
method is used in conjunction with constraint objects created by the
<tt>Is</tt> factor class:

<code>
  Assert::that('Hello', Is::equalTo('Hello'));
</code>

The "Is" factory
~~~~~~~~~~~~~~~~
<code>
  class Is extends Object {
    public static function equalTo($value) { ... }
    public static function theSameAs($value) { ... }
    public static function not() { ... }
    public static function either() { ... }
    public static function between($lo, $hi) { ... }
    public static function greaterThan($lo) { ... }
    public static function lessThan($hi) { ... }
    public static function null() { ... }
    public static function false() { ... }
    public static function true() { ... }
    public static function anInstanceOf($type) { ... }
  }
</code>

Security considerations
-----------------------
None


Speed impact
------------
None, optional API


Dependencies
------------
None


Related documents
-----------------
Flexible JUnit assertions with assertThat()
* http://joe.truemesh.com/blog/000511.html

Overlay:
* http://xp-framework.net/rfc/contrib/rfc0199.xar

JMock constraints:
* http://jmock.org/docs/javadoc/org/jmock/core/Constraint.html

Comments
--------

<EOF>

<commit_msg>- Is -> Should<commit_after>RFC 0199: Assertions
========================================================================
$Id$

@authors: friebe
@created: Tue Dec 22 20:15:04     2009
@status: draft
@target:  5.7.10
@category: unittest

Scope of Change
---------------
A new API for assertions will be added: <tt>Assert::that()</tt>.


Rationale
---------
More verbose error messages for the failure case.


Functionality
-------------
Instead of using the <tt>unittest.TestCase</tt> class' methods such as 
<tt>assertEquals()</tt> and friends the static <tt>Assert::that()</tt>
method is used in conjunction with constraint objects:

API
~~~
<code>
  class Assert extends Object {
    public static void that($value, Constraint $constraints);
  }
  
  class Should extends Object {
    public static Constraint equal($value) { ... }
    public static Constraint contain($value) { ... }
    public static Constraint startWith($slice) { ... }
    public static Constraint endWith($slice) { ... }
    public static Constraint match($pattern) { ... }

    public static BeConstraint be() { ... }
    public static ShouldConstraint not() { ... }
    public static ShouldConstraint either() { ... }
    public static ShouldConstraint neither() { ... }
  }
    
  class Constraint extends Object {
    public ShouldConstraint $and;
    public ShouldConstraint $or;
    public ShouldConstraint $nor;
  }

  class ShouldConstraint extends Constraint {
    public Constraint equal($value) { ... }
    public Constraint contain($value) { ... }
    public Constraint startWith($slice) { ... }
    public Constraint endWith($slice) { ... }
    public Constraint match($pattern) { ... }

    public BeConstraint $be;
  }
  
  class BeConstraint extends Constraint {
    public Constraint $empty;
    public Constraint $null;
    public Constraint $false;
    public Constraint $true;

    public Constraint theSameAs($value) { ... }
    public Constraint equalTo($value) { ... }
    public Constraint greaterThan($lo) { ... }
    public Constraint lessThan($hi) { ... }
    public Constraint between($lo, $hi) { ... }
    public Constraint anyOf($values...) { ... }
    public Constraint oneOf($values...) { ... }

    public Constraint ofType($type) { ... }
    public Constraint anInstanceOf($type) { ... }
  }
</code>

Examples
~~~~~~~~
<code>
  Assert::that(3, Should::equal(3));
  Assert::that($recipients, Should::contain(new InternetAddress('<EMAIL>')));
  Assert::that('Hello', Should::startWith('H')->and->endWith('o'));
  Assert::that($name, Should::match('/[a-z]/i'));
  Assert::that(NULL, Should::be()->null);
  Assert::that($class->getMethods(), Should::not()->be->empty);
  Assert::that($expr, Should::neither()->equal(2)->nor->be->lessThan(0));
</code>


Security considerations
-----------------------
None


Speed impact
------------
None, optional API


Dependencies
------------
None


Related documents
-----------------
Flexible JUnit assertions with assertThat()
* http://joe.truemesh.com/blog/000511.html

Overlay:
* http://xp-framework.net/rfc/contrib/rfc0199.xar

JMock constraints:
* http://jmock.org/docs/javadoc/org/jmock/core/Constraint.html

NUnit 2.4 Assert Syntax - the Latest Developments
* http://nunit.net/blogs/?p=44

Comments
--------

<EOF>


{'fraction_non_alphanumeric': 0.21035919825362176, 'fraction_numerical': 0.013494741020043659, 'mean_word_length': 3.0384615384615383, 'pattern_counts': {'":': 0, '<': 32, '<?xml version=': 0, '>': 43, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5956696', 'n_tokens_mistral': 1514, 'n_tokens_neox': 1418, 'n_words': 400}