+1 tests serve as documentation (for developers)
I think they don't serve as documentation to others than devs in
their source code form, because tests and their source is normally
not easy "accessible" to others.
But what about if we generate "documentation" in an accessible
format and publish somewhere? (similar like BDD does)
In my team we generate documentation with a T4 template that clears
out all C# noise and spits out a HTML document.
1 test sample that gets converted to documentation
Feature: OnlyBidFullIncrements
Lot1 ActualPrice = 50
Lot1 BidIncrement = 50
MarketOp Change AuctionState: Catalogued
Anna enters LimitBid: Lot1, 145
MarketOp Change AuctionState: Active
Bob places Bid: Lot1, 100
//Note: Anna is getting it for 100, because it is less than 1 bid
increment away
Expect HoldingBidder AndPrice: Anna, Lot1, 100
These tests / HTML documents act as documentation for us
(developers) and when we talk/explain to others (PO and
stakeholders)...
>>What contexts are tests as documenation "good"/ "helpful" etc...
for?
#1
>>Learning a new system through tests.
To me, a system is new if I haven't seen it for a while ;-)
So re-learning how the system works, is another context where they
are helpful..
I learn what the edge cases are, what expected input is, and which
collaborator the SUT depends on.
#2
What about documenting performance goals?
Example: Create an integration test that hits a certain a webpage
and excepts a result in less than 2 seconds.
This test could act as documentation for that performance goal.
#3
Usage of an API can be nicely documented through tests as well
>> * As for learning a new system goes, tests as documentation don't
>>offer historical explanation. For example, the roads not taken
which helps paint the
>>pictue of why the system is the way that it is.
Nice idea, but I cant really think of a practical usage. By writing
your tests in a TDD manner, there is not really a road not taken...
my 2c
.peter.gfader.
http://blog.gfader.com
On Wed, Mar 2, 2011 at 4:14 AM, Frank Schwieterman
<[email protected]> wrote:
I think the point about unit testing vs integration testing is true,
what you test is what you've documented. So unit tests tell a
different story then integration tests.
I just wanted to chip in that I do use tests as documentation, but
not as something I read through. Its a reference I navigate with
Reflector or Resharper. When I have a question about a method or
class, I will find references to it in the tests to understand its
intent and use.
On Tue, Mar 1, 2011 at 8:09 AM, Alan Ridlehoover
<[email protected]> wrote:
> Good conversation. One point I think is missing is this:
> Unit tests make good documentation for individual methods/
classes. But,
> automated functional/acceptance tests make better documentation
for the
> system as a whole. And, yes, I've seen environments where the
Fitnesse
> tests were the documentation for the system. I've also seen STiQ
tests used
> that way (with less success), and WatiN-based NUnit tests (with good
> success).
> Alan
> On Feb 27, 2011, at 8:08 PM, Michael Ibarra wrote:
>
> Hi Aeden,
> I've never seen tests written and organized well enough to serve as
> documentation (for neither developers nor "the business").
However, I do my
> best to write and organize my tests to be intention revealing.
> But that's not why I write tests. I write tests primarily because:
1. I want
> to make sure that the code I write works the way it's supposed to,
2. I want
> to make sure that adding new features doesn't introduce any bugs,
3. I don't
> write(and therefore maintain) any more code than is necessary to
implement
> the feature. 4. I find that writing my tests first helps me write
cleaner,
> more S.O.L.I.D. code.
> I want other developers to be able to read my tests and understand
what my
> code does, but that's just a side effect of well written and well
organized
> tests.
> Anyway, that's my 2 cents. Hope that helps.
> Mike
>
> On Sun, Feb 27, 2011 at 7:13 PM, Aeden Jameson <[email protected]
>
> wrote:
>>
>> I'm curious how much stock people on this list put in the idea that
>> tests serve as documentation.
>>
>> --
>> Cheers,
>> Aeden
>>
>> Blog : http://aedenjameson.blogspot.com/
>> Linked In: http://www.linkedin.com/in/aedenjameson
>> Blah Blah Blah: http://www.twitter.com/daliful
>>
>> --
>> You received this message because you are subscribed to the
Google Groups
>> "Seattle area Alt.Net" group.
>> To post to this group, send email to
[email protected].
>> To unsubscribe from this group, send email to
>> [email protected].
>> For more options, visit this group at
>> http://groups.google.com/group/altnetseattle?hl=en.
>>
>
>
>
> --
> ********************************
> Michael Ibarra
> [email protected]
> @bm2yogi
> http://dev.bm2yogi.com
>
> --
> You received this message because you are subscribed to the Google
Groups
> "Seattle area Alt.Net" group.
> To post to this group, send email to [email protected].
> To unsubscribe from this group, send email to
> [email protected].
> For more options, visit this group at
> http://groups.google.com/group/altnetseattle?hl=en.
>
> --
> You received this message because you are subscribed to the Google
Groups
> "Seattle area Alt.Net" group.
> To post to this group, send email to [email protected].
> To unsubscribe from this group, send email to
> [email protected].
> For more options, visit this group at
> http://groups.google.com/group/altnetseattle?hl=en.
>
--
You received this message because you are subscribed to the Google
Groups "Seattle area Alt.Net" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to [email protected]
.
For more options, visit this group at http://groups.google.com/group/altnetseattle?hl=en
.
--
.peter.gfader.
http://blog.gfader.com/
http://twitter.com/peitor
--
You received this message because you are subscribed to the Google
Groups "Seattle area Alt.Net" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to [email protected]
.
For more options, visit this group at http://groups.google.com/group/altnetseattle?hl=en
.
