Re: Writing New Constraints for NUnit
"Simone Busoli" <[email protected]> Mon, 8 Sep 2008 01:17:01 +0200
| Newsgroups | gmane.comp.windows.dotnet.nunit.user |
|---|---|
| Message-ID | <[email protected]> |
--===============0839757982== Content-Type: multipart/alternative; boundary="----=_Part_68188_8901914.1220829421337" ------=_Part_68188_8901914.1220829421337 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline Thanks for the guide. I'm trying to write the BinarySerializableConstraint but I'm having some issues with building and testing NUnit. So far I had been able to build and run tests from within VS via TD.NET, but now I noticed that base test classes use NUnit 2.5 features so I had to rely on something else. I tried building NUnit with nant but no success, it complaints about missing files, specifically a Factory[something].cs. Then, since I can run the build with VS 2008, I downloaded NUnit 2.5 alpha 3 (won't trust the build on my machine) and tried with that, but I'm getting red all over the place in the tests for the constraints, while everything's green for the other stuff in Tests and Syntax namespaces. At a quick look it seems that what's failing are the tests defined in the ConstraintTestBase class (FailsWithBadValues, ProvidesProperFailureMessage), those using the TestCases attribute in other words. On Sun, Sep 7, 2008 at 7:35 PM, Charlie Poole <[email protected]> wrote: > Hi All, > > I've been asked to provide more info on the increasingly complicated > process of adding a new constraint to NUnit. Since I still expect > it to change - and hopefully get simpler - I'm doing it on these > mailing lists as "current but subject to change" information. > > This is basically a "how-to" but I've added a postscript about > why the design is as it is at the end. > > Actually, adding a constraint is easy. It's documented here: > http://nunit.org/?p=customConstraints&r=2.5 It gets more > complicated when you also want to work with the syntax > of NUnit's fluent interface for Asserts. > > I generally write constraints test first, jumping between the > tests and the constraint and between the syntax tests and > the syntactic elements. That's hard to describe, so I'll just > tell you what's needed at the end here. > > 1. The Constraint > I assume you're writing a simple constraint, one that does > not operate on other constraints. Inherit your constraint > class from Constraint and override the two abstract members > Match() and WriteDescriptionTo(). Be sure to set the value > of the protected field "actual" in your Match method, since > that is used in any error message. Depending on the constraint > you are writing, you might need to override other methods, but > leave them alone unless you need to do it. > > If your constraint has a generic variation, be sure to define > it within the scope of an #if NET_2_0 condition. If it operates > on any collections, try to make it work with IEnumerable > only and avoid copying the collection. > > An important rule for constraints is to check for invalid > arguments and throw an exception. Do NOT just return false. > While this may work for simple cases, it will mess up more > complicated usage where constraints are combined with > various operators. And, of course, it may hide an error. > > 2. Constraint Tests > Derive one or more classes from ConstraintTestBase. Each of > those will be used to test one instance of the constraint. > How many you need depend on how many variations there are > within your constraint. Be sure to create separate tests > for generic variations -within an #if statement. > > Write any extra tests you need, adding them to the same > classes or within a separate fixture. > > NOTE: If you stop here, your constraint is useable by > creating it with new. You can write statements like: > Assert.That( xxx, new MyConstraint(...) ); > > NOTE: See below if your constraint takes modifiers > > 3. Syntactic Elements > You will need to pick one or more key words for use > in the NUnit syntax. Pick something that will be > meaningful while keeping it reasonably short. > > Currently, you must add your syntactic element in > three places. I'm looking at using code generation > to eliminate this duplication. The following > classes need to be updated: > > * PartialConstraintExpression - look at how other > simple constraints are implemented here. If > your constraint takes modifiers, see below. > Otherwise, you will just need a method similar > to this one for TypeOf: > > public ConstraintExpression TypeOf(Type expectedType) > { > return this.Append(new ExactTypeConstraint(expectedType)); > } > > * Is/Has - you decide which is better, or consult > on the list if you're convinced that you need > a new class. Add a method similar to this: > > public static ConstraintExpression TypeOf(Type expectedType) > { > return new PartialConstraintExpression().TypeOf(expectedType); > } > > * ConstraintFactory: Add a method similar to this: > > public ConstraintExpression TypeOf(Type expectedType) > { > return Is.TypeOf(expectedType); > } > > NOTE: It's important to keep the actual logic in the > PartialConstraintBuilder class, with the others depending > on it. > > NOTE: If your constraint takes no args, use properties > rather than methods - it's easier to read. > > 4. Syntax Tests > Derive one or more classes from SyntaxTest. You will > need one for each different syntax you need to test. > If you forget to add code to any of the three classes > above, these tests will tell you. > > At this point you're done... UNLESS you want to add > modifiers to your class. If your constraint will take > any modifiers, I suggest you do all of the above first, > then add the first one and make it work, then add > the others. Come back to this note if/when you want > to add a modifier... > > Welcome Back! > > In the NUnit syntax, a modifier is a property or method > that returns the object itself, after making some sort > of state change. Existing examples of modifiers are > Within(), IgnoreCase and Descending. Here's a simple > modifier: > > public EqualConstraint IgnoreCase > { > get { caseInsensitive = true; return this; } > } > > With the above addition, it's possible to write > new EqualConstraint("hello").IgnoreCase > but NOT > Is.EqualTo("hello").IgnoreCase > > In order to make the syntax work, it's currently > necessary to create a ConstraintModifier class. > These classes inherit from ConstraintModifier > and are usually implemented as nested classes > within the constraint itself, so as to allow > access to private members of the constraint. > > Here's a simplified version of the one for > EqualConstraint: > > public class Modifier : ConstraintModifier > { > private EqualConstraint constraint; > > public Modifier(EqualConstraint constraint, > ConstraintExpression builder) > : base(constraint, builder) > { > this.constraint = constraint; > } > > public Modifier IgnoreCase > { > get { constraint.caseInsensitive = true; return this; } > } > } > > After implementing the above, the three syntax classes > need to be changed so our methods return EqualConstraint.Modifier. > ConstraintFactory and Is/Has require no further changes but > PartialConstraintExpression will now look like this: > > public EqualConstraint.Modifier EqualTo(object expected) > { > EqualConstraint constraint = new EqualConstraint(expected); > return new EqualConstraint.Modifier(constraint, > this.Append(constraint)); > } > > That's "all" there is to it! :-) > > Charlie > > Theoretical PostScript: > > In case you wonder Why we neeed all the classes: > > We want to provide a good object model, while *at*the*same*time* > having only reasonable choices appear in the intellisense. And > we want whatever you can compile to make sense as much as > is possible, so that there aren't too many runtime checks. > > So we need separate PartialConstraintExpression and > ConstraintExpression classes to make sure you can't > enter ...And.And... or ...Null.Null... and similar > meaningless stuff. > > We need Is/Has to provide static methods to get the > expression started. > > We need ConstraintFactory, to supply instance methods > for use by those who prefer to derive test classes > from AssertionHelper. We could eliminnate that > class by eliminating the feature. > > In particular, the Modifier classes are needed because we > are dealing with a ConstraintExpression, but want the > choices offered to the user to represent those provided > for an Equal Constraint. The Modifier class ties together > the whole expression and the "leading edge" constraint > in a way that lets us have both. If the user ends the > expression, the Modifier's implementation of IConstraint > is used. If the user types "IgnoreCase" the EqualConstraint > is used. If the user types "And" or "Or", that's handled > by the ConstraintExpression. > > I'm working on a few approaches to this extra class. > > > > > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win great > prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Nunit-users mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/nunit-users > ------=_Part_68188_8901914.1220829421337 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline <div dir="ltr">Thanks for the guide. I'm trying to write the BinarySerializableConstraint but I'm having some issues with building and testing NUnit. So far I had been able to build and run tests from within VS via <a href="http://TD.NET">TD.NET</a>, but now I noticed that base test classes use NUnit 2.5 features so I had to rely on something else. I tried building NUnit with nant but no success, it complaints about missing files, specifically a Factory[something].cs. Then, since I can run the build with VS 2008, I downloaded NUnit 2.5 alpha 3 (won't trust the build on my machine) and tried with that, but I'm getting red all over the place in the tests for the constraints, while everything's green for the other stuff in Tests and Syntax namespaces. At a quick look it se ems that what's failing are the tests defined in the ConstraintTestBase class (FailsWithBadValues, ProvidesProperFailureMessage), those using the TestCases attribute in other words. <br> <br><div class="gmail_quote">On Sun, Sep 7, 2008 at 7:35 PM, Charlie Poole <span dir="ltr"><<a href="mailto:[email protected]">[email protected]</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> Hi All,<br> <br> I've been asked to provide more info on the increasingly complicated<br> process of adding a new constraint to NUnit. Since I still expect<br> it to change - and hopefully get simpler - I'm doing it on these<br> mailing lists as "current but subject to change" information.<br> <br> This is basically a "how-to" but I've added a postscript about<br> why the design is as it is at the end.<br> <br> Actually, adding a constraint is easy. It's documented here:<br> <a href="http://nunit.org/?p=customConstraints&r=2.5" target="_blank">http://nunit.org/?p=customConstraints&r=2.5</a> It gets more<br> complicated when you also want to work with the syntax<br> of NUnit's fluent interface for Asserts.<br> <br> I generally write constraints test first, jumping between the<br> tests and the constraint and between the syntax tests and<br> the syntactic elements. That's hard to describe, so I'll just<br> tell you what's needed at the end here.<br> <br> 1. The Constraint<br> I assume you're writing a simple constraint, one that does<br> not operate on other constraints. Inherit your constraint<br> class from Constraint and override the two abstract members<br> Match() and WriteDescriptionTo(). Be sure to set the value<br> of the protected field "actual" in your Match method, since<br> that is used in any error message. Depending on the constraint<br> you are writing, you might need to override other methods, but<br> leave them alone unless you need to do it.<br> <br> If your constraint has a generic variation, be sure to define<br> it within the scope of an #if NET_2_0 condition. If it operates<br> on any collections, try to make it work with IEnumerable<br> only and avoid copying the collection.<br> <br> An important rule for constraints is to check for invalid<br> arguments and throw an exception. Do NOT just return false.<br> While this may work for simple cases, it will mess up more<br> complicated usage where constraints are combined with<br> various operators. And, of course, it may hide an error.<br> <br> 2. Constraint Tests<br> Derive one or more classes from ConstraintTestBase. Each of<br> those will be used to test one instance of the constraint.<br> How many you need depend on how many variations there are<br> within your constraint. Be sure to create separate tests<br> for generic variations -within an #if statement.<br> <br> Write any extra tests you need, adding them to the same<br> classes or within a separate fixture.<br> <br> NOTE: If you stop here, your constraint is useable by<br> creating it with new. You can write statements like:<br> Assert.That( xxx, new MyConstraint(...) );<br> <br> NOTE: See below if your constraint takes modifiers<br> <br> 3. Syntactic Elements<br> You will need to pick one or more key words for use<br> in the NUnit syntax. Pick something that will be<br> meaningful while keeping it reasonably short.<br> <br> Currently, you must add your syntactic element in<br> three places. I'm looking at using code generation<br> to eliminate this duplication. The following<br> classes need to be updated:<br> <br> * PartialConstraintExpression - look at how other<br> simple constraints are implemented here. If<br> your constraint takes modifiers, see below.<br> Otherwise, you will just need a method similar<br> to this one for TypeOf:<br> <br> public ConstraintExpression TypeOf(Type expectedType)<br> {<br> return this.Append(new ExactTypeConstraint(expectedType));<br> }<br> <br> * Is/Has - you decide which is better, or consult<br> on the list if you're convinced that you need<br> a new class. Add a method similar to this:<br> <br> public static ConstraintExpression TypeOf(Type expectedType)<br> {<br> return new PartialConstraintExpression().TypeOf(expectedType);<br> }<br> <br> * ConstraintFactory: Add a method similar to this:<br> <br> public ConstraintExpression TypeOf(Type expectedType)<br> {<br> return Is.TypeOf(expectedType);<br> }<br> <br> NOTE: It's important to keep the actual logic in the<br> PartialConstraintBuilder class, with the others depending<br> on it.<br> <br> NOTE: If your constraint takes no args, use properties<br> rather than methods - it's easier to read.<br> <br> 4. Syntax Tests<br> Derive one or more classes from SyntaxTest. You will<br> need one for each different syntax you need to test.<br> If you forget to add code to any of the three classes<br> above, these tests will tell you.<br> <br> At this point you're done... UNLESS you want to add<br> modifiers to your class. If your constraint will take<br> any modifiers, I suggest you do all of the above first,<br> then add the first one and make it work, then add<br> the others. Come back to this note if/when you want<br> to add a modifier...<br> <br> Welcome Back!<br> <br> In the NUnit syntax, a modifier is a property or method<br> that returns the object itself, after making some sort<br> of state change. Existing examples of modifiers are<br> Within(), IgnoreCase and Descending. Here's a simple<br> modifier:<br> <br> public EqualConstraint IgnoreCase<br> {<br> get { caseInsensitive = true; return this; }<br> }<br> <br> With the above addition, it's possible to write<br> new EqualConstraint("hello").IgnoreCase<br> but NOT<br> Is.EqualTo("hello").IgnoreCase<br> <br> In order to make the syntax work, it's currently<br> necessary to create a ConstraintModifier class.<br> These classes inherit from ConstraintModifier<br> and are usually implemented as nested classes<br> within the constraint itself, so as to allow<br> access to private members of the constraint.<br> <br> Here's a simplified version of the one for<br> EqualConstraint:<br> <br> public class Modifier : ConstraintModifier<br> {<br> private EqualConstraint constraint;<br> <br> public Modifier(EqualConstraint constraint,<br> ConstraintExpression builder)<br> : base(constraint, builder)<br> {<br> this.constraint = constraint;<br> }<br> <br> public Modifier IgnoreCase<br> {<br> get { constraint.caseInsensitive = true; return this; }<br> }<br> }<br> <br> After implementing the above, the three syntax classes<br> need to be changed so our methods return EqualConstraint.Modifier.<br> ConstraintFactory and Is/Has require no further changes but<br> PartialConstraintExpression will now look like this:<br> <br> public EqualConstraint.Modifier EqualTo(object expected)<br> {<br> EqualConstraint constraint = new EqualConstraint(expected);<br> return new EqualConstraint.Modifier(constraint,<br> this.Append(constraint));<br> }<br> <br> That's "all" there is to it! :-)<br> <br> Charlie<br> <br> Theoretical PostScript:<br> <br> In case you wonder Why we neeed all the classes:<br> <br> We want to provide a good object model, while *at*the*same*time*<br> having only reasonable choices appear in the intellisense. And<br> we want whatever you can compile to make sense as much as<br> is possible, so that there aren't too many runtime checks.<br> <br> So we need separate PartialConstraintExpression and<br> ConstraintExpression classes to make sure you can't<br> enter ...And.And... or ...Null.Null... and similar<br> meaningless stuff.<br> <br> We need Is/Has to provide static methods to get the<br> expression started.<br> <br> We need ConstraintFactory, to supply instance methods<br> for use by those who prefer to derive test classes<br> from AssertionHelper. We could eliminnate that<br> class by eliminating the feature.<br> <br> In particular, the Modifier classes are needed because we<br> are dealing with a ConstraintExpression, but want the<br> choices offered to the user to represent those provided<br> for an Equal Constraint. The Modifier class ties together<br> the whole expression and the "leading edge" constraint<br> in a way that lets us have both. If the user ends the<br> expression, the Modifier's implementation of IConstraint<br> is used. If the user types "IgnoreCase" the EqualConstraint<br> is used. If the user types "And" or "Or", that's handled<br> by the ConstraintExpression.<br> <br> I'm working on a few approaches to this extra class.<br> <br> <br> <br> <br> <br> <br> -------------------------------------------------------------------------<br> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge<br> Build the coolest Linux based applications with Moblin SDK & win great prizes<br> Grand prize is a trip for two to an Open Source event anywhere in the world<br> <a href="http://moblin-contest.org/redirect.php?banner_id=100&url=/" target="_blank">http://moblin-contest.org/redirect.php?banner_id=100&url=/</a><br> _______________________________________________<br> Nunit-users mailing list<br> <a href="mailto:[email protected]">[email protected]</a><br> <a href="https://lists.sourceforge.net/lists/listinfo/nunit-users" target="_blank">https://lists.sourceforge.net/lists/listinfo/nunit-users</a><br> </blockquote></div><br></div> ------=_Part_68188_8901914.1220829421337-- --===============0839757982== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ --===============0839757982== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Nunit-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/nunit-users --===============0839757982==--