+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 1. Lot1 ActualPrice = 50 Lot1 BidIncrement = 50 2. MarketOp Change AuctionState: Catalogued 3. Anna enters LimitBid: Lot1, 145 4. MarketOp Change AuctionState: Active 5. Bob places Bid: Lot1, 100 6. //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.
