Better docs

[searls]

Start the long task of writing better docs.

• Installation
  • Node.js
  • Browser
    • Curl
    • npm
    • bower
  • Configuring with test library
    • Resetting testdouble.js
• How to use test double
  • The purpose of test doubles
    • To test interactions in code whose primary responsibility is facilitating the collaboration of sevveral dependencies ("a collaborator")
    • Not intended, necessarily, to fake out third party / integrations, the focus is to unit tests, specifically to support isolated TDD workflows (link to discovery testing)
  • Getting Started
    • Start with a subject, which needs a few deps (stub, intermediary, side effect)
    • Write the test setting those up with true fakes
    • Make the test pass
    • Ample links to creation, stubbing, verifying
  • All about creating
    • Functions
      • Anonymous
      • Named
    • Objects
      • Arrays of function names
      • Prototype mirroring
      • Proxy (Anonymous or Named)
  • All about stubbing
    • Definition
    • Simple stub example
    • Single arg
    • Multi arg
    • return sequences
    • why not unconditional stubbing?
    • matchers
    • supported options
  • All about verifying
    • Simple verification
    • Single arg
    • Multi arg
    • Matchers
    • using argument captors
    • supported options
  • All about td.replace (node.js only)
    • Warning about node 0.10 incompatibility
    • Example with function bags
    • example of functions
    • example of prototype constructors
    • explain why modules are not supported
    • explain how quibble works
  • custom matchers
  • Debugging test doubles
  • Plugins / Extensions
    • testdouble-chai
    • testdouble-jasmine
  • Frequently asked questions
• drop an outline like this one into the README and link back to all the doc pages

[hanneskaeufler]

I like how that reads! Just a small thought, one of the beauties of delegating to collaborators is that the method under test does not need to care for implementation details of the invoked methods. So in practice I would not say it("POSTs a random problem") but rather it("saves and submits the randomly generated problem") (or something along those lines) because the generate method does not/should not need to care about the method of transportation of saveProblem. Though I get that's not really in the focus of the getting started guide ... so rock on!

[searls]

Thanks for the comment. I might make that change. In reality, a lot of times, as developers we're tasked with some implementation details baked into the requirements we're handed (especially relating to protocols and the interaction of our work product with other technologies). For that reason, POSTing in an example like this isn't necessarily an implementation detail of the thing under test, since it affects extrinsic behavior.

In cases like the above, I actually value a little bit of technical telegraphing in the test, because a vague business-ey description doesn't add much. (And to anticipate one reply, if an extrinsic change were ever made to this dependency such that it'd use a websocket instead of a POST, my workflow with test doubles would be to delete the dependency and its entire sub-tree of units, so I'm not too worried about comment rot)

[hanneskaeufler]

Thanks for the elaboration! I definately agree on some technical telegraphing (love the expression 🎉). You'd likely also write some tests for the saveProblem method/class, and this is where the POST mention would be the most fitting I guess? This would leave the generate method and its test/comment entirely untouched from the change.

[searls]

BOOM. Finally done.