From b09393b8b3e602141c8cbf136af6bc004295dd1b Mon Sep 17 00:00:00 2001 From: Thomas PIERRAIN Date: Fri, 8 Mar 2013 08:39:51 +0100 Subject: [PATCH] Updates the markdown documentation. --- Backlog.md | 1 + DevDoD.md | 9 +++++---- ReadMe.md | 28 ++++++++++++++++++++++------ UseCases.md | 2 +- 4 files changed, 29 insertions(+), 11 deletions(-) diff --git a/Backlog.md b/Backlog.md index acbb8f18..a9d47304 100644 --- a/Backlog.md +++ b/Backlog.md @@ -6,5 +6,6 @@ NFluent backlog + may be interesting to introduce t4 template to generate the various versions of this entry-point + Publish v1.0 into nuget + Make every FluentExceptionMessage a two liners ++ Adds new assertion methods to complete the offer of NFluent + Introduces And and Or operators for the IFluentAssert interface? + Spread the word about the library to have feedback and first users \ No newline at end of file diff --git a/DevDoD.md b/DevDoD.md index 74606f7b..db6fd9fb 100644 --- a/DevDoD.md +++ b/DevDoD.md @@ -9,7 +9,7 @@ These are the rules that should be followed in order to contribute to this proje 3. 100% of test coverage for the NFluent project + Test names should be clear enough to know what is in stakes here (this is why I disable the "ElementsMustBeDocumented" StyleCop rule for tests) 4. With (of course) all unit tests passed ;-) -5. The entire build (i.e. including all the unit tests execution) takes less than 2 minutes +5. The entire build (i.e. including all the unit tests execution) takes less than a minute Original intentions @@ -18,9 +18,10 @@ Original intentions Before modifying this library, it is very important to keep in mind that __this library is designed to produce fluent assertions at the end!__ Thus, it means that: -+ __names__ of the extension methods __should be chosen carefully__ (to smartly embrace the intellisense autocompletion mechanism) -+ every __extension method that don't succeed should throw a FluentAssertionException__ to make your favorite unit test framwork Assert.That() statement fails __with a clear status message__ ++ __names__ of the assertion methods __should be chosen carefully__ and smartly embrace the intellisense autocompletion mechanism (i.e. the 'dot' experience). ++ every __assertion method should return void and should throw a FluentAssertionException when failing__ (to make your favorite unit test framwork fail __with a clear status message__. + the message of all the FluentAssertException you throw should be clear as crystal, but also compliant with the ready-to-be-copied-and-paste-for-arrays-or-collections-initialization-purpose objective of NFluent ++ Follow the previous documentation semantic and syntax for every new method. Also, and to stay coherent with the equivalent **FEST fluent assert** Java library (interesting for people which are coding in those 2 platforms): -+ Thus, before introducing a new extension method, check the existence of a method name for the same thing within the java library (http://fest.easytesting.org/). ++ Thus, before introducing a new method, check the existence of a method name for the same thing within the java library (http://fest.easytesting.org/). diff --git a/ReadMe.md b/ReadMe.md index e123d48e..85929080 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -12,16 +12,17 @@ __NFluent will make your tests__: + __helpful to reverse engineer legacy code__: indeed, temporarily write an on-purpose failing assert on a legacy method, so you can understand it and leverage on the "ready-to-be-copied-and-paste-for-arrays-or-collections-initialization-purpose" NFluent assert failure messages. + __less error-prone__: indeed, no more confusion about the order of the "expected" and "actual" values. -NFluent is __highly inspired by the awesome Java FEST Fluent__ assertion/reflection library (http://fest.easytesting.org/) +NFluent is __highly inspired by the awesome Java FEST Fluent__ assertion/reflection library (http://fest.easytesting.org/). - -Disclaimer ----------- +NFluent & unit test frameworks +------------------------------- __NFluent is not coupled to any .NET unit test framework. It is fully designed to work in collaboration with your favorite one.__ -With NUnit for instance, you can simply use all the NFluent method extensions from any NUnit Assert.That(bool condition) statement. +Your favorite unit test framework (e.g. NUnit, xUnit, ...) will still handle the test identification, execution & Co, but you will simply now replace your usage of its Assert class by the NFluent assertions statements. That's all! -If you are using another .NET unit tests framework which don't provide such nice and simple Assert.That() bootstraping method (e.g. xUnit), you can use the one gracefully provided by the NFluent library ;-) +Uses cases +---------- +__[NFluent use cases are available here](./UseCases.md)__. Usage sample ------------ @@ -64,12 +65,27 @@ with NFluent, you can also write assertions like this: // assertThat(inn.getItems()).onProperty("name").containsExactly("+5 Dexterity Vest", "Aged Brie", "Elixir of the Mongoose", "Sulfuras, Hand of Ragnaros", "Backstage passes to a TAFKAL80ETC concert", "Conjured Mana Cake"); ``` +Why NFluent, and not another .NET fluent assertion framework? +---------------------------------------------------------------------------- ++ Because you don't think that writing a lambda expression within an assertion statement is really a fluent experience (neither a fluent reading experience too). ++ Because this API is completely driven by the __[super-duper-happy-path](https://github.com/NancyFx/Nancy/wiki/Introduction)__ principle to fluent your .NET TDD-practitioner life. For instance, we consider the 'dot' autocompletion experience as crucial. Thus, it should not be a painful experience (intellisense flooding). ++ Because you dislike the SubjectUnderTest.Should()... syntax like me (which is not semantically as strong as the Assert or Check one). ++ And because you like *killer feature* such as the Properties() extension method for IEnumerable for instance (as showed within the usage sample above). + - - - Newsgroup --------- For any comment, remark or question, please use the __[NFluent-Discuss google group](https://groups.google.com/forum/#!forum/nfluent-discuss)__. +BackLog +------- +Nfluent __[backlog is available here](./BackLog.md)__ + +Quality chart +------------- +You want to contribute? See the __[NFluent definition of done for development](./DevDoD.md)__ before. But welcome! + - - - [thomas@pierrain.net](mailto:thomas@pierrain.net) / February 6th 2013 \ No newline at end of file diff --git a/UseCases.md b/UseCases.md index cdf399b0..24cb7361 100644 --- a/UseCases.md +++ b/UseCases.md @@ -6,7 +6,7 @@ NFluent use cases As a Developer, I want to be able to rely on the autocompletion when I write test assertions So that I can write them in a fluent manner, and without any hesitation about the kind of assertion that is possible and available regarding my current System Under Test (SUT). - + 2. Provide a fluent reading experience for unit tests -----------------------------------------------------