Add some developer docs for writing tests.

Add some developer docs for writing tests.

Obviously there is a lot that could be written, but this
is a start.

https://code.launchpad.net/~thumper/juju-core/testing-docs/+merge/218732

(do not edit description out of merge proposal)

[thumper, 2014-05-08 03:46:09]

Please take a look.

[wallyworld, 2014-05-08 03:56:56]

A great start.
I'd also mention github.com/juju/testing/checkers
LGTM. We should get this in and iterate on it.

[menn0, 2014-05-08 04:38:58]

Minor fixes

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt
File doc/how-to-write-tests.txt (right):

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:165: To create your new test suite composing one of
the following, you can
Clearer as: 

To create a new suite composed of one or more of the suites above, you can do
something like:

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:207: in the compisition tree, there are a few very
helpful functions.
composition

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:223: PatchValue works with any matching type. This
includes function variables.
Is it possible to patch methods? I'm guessing it isn't, but if it is could you
add an example here?

[thumper, 2014-05-08 05:05:38]

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt
File doc/how-to-write-tests.txt (right):

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:165: To create your new test suite composing one of
the following, you can
On 2014/05/08 04:38:58, menn0 wrote:
> Clearer as: 
> 
> To create a new suite composed of one or more of the suites above, you can do
> something like:

Done.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:207: in the compisition tree, there are a few very
helpful functions.
On 2014/05/08 04:38:58, menn0 wrote:
> composition

Done.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:223: PatchValue works with any matching type. This
includes function variables.
On 2014/05/08 04:38:58, menn0 wrote:
> Is it possible to patch methods? I'm guessing it isn't, but if it is could you
> add an example here?

No, you can't patch methods.  You do that by using interfaces, and mocking them
out.

[fwereade, 2014-05-08 05:34:49]

This is awesome. Not all my comments are necessarily directly actionable, in
that they're complaints about our current testing, but perhaps you can find some
way to work their intent in usefully.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt
File doc/how-to-write-tests.txt (right):

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:119: // a pointer to that variable so we can patch it
in the tests.
formatting

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:151: github.com/juju/testing, which brings in the
CleanupSute from the same.
s/Sute/Suite/

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:159: JUJU_ENV, and JUJU_LOGGING_CONFIG environment
variables.
The FakeHomeSuite should generally not be used, because it assumes a context of
a running (cmd/juju) client; almost all the code should avoid making this
assumption, because it's actually generally going to run on an API server.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:162: api server.
The JujuConnSuite is all fucked up, and should be used when you just don't care
about having coherent context available, you just kinda want everything and
don't want to think too hard. State server? Client? Both? Whooo! Who cares!

Yeah, we should fix this; but in the meantime I want people to know it's at
least somewhat bad/wrong, because then *maybe* someone will take it upon
themselves to extract a saner subset of the functionality and start using that;
as it is it's all too easy to just allow the rot to gently spread without even
knowing that's what you're doing.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:215: // of the test.
Really, FWIW, I think we should always be clearing the env at the very start of
a test.

[thumper, 2014-05-08 22:34:42]

Please take a look.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt
File doc/how-to-write-tests.txt (right):

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:119: // a pointer to that variable so we can patch it
in the tests.
On 2014/05/08 05:34:49, fwereade wrote:
> formatting

Done.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:151: github.com/juju/testing, which brings in the
CleanupSute from the same.
On 2014/05/08 05:34:49, fwereade wrote:
> s/Sute/Suite/

Done.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:159: JUJU_ENV, and JUJU_LOGGING_CONFIG environment
variables.
On 2014/05/08 05:34:49, fwereade wrote:
> The FakeHomeSuite should generally not be used, because it assumes a context
of
> a running (cmd/juju) client; almost all the code should avoid making this
> assumption, because it's actually generally going to run on an API server.

Perhaps that was the original intent, but it has been extended somewhat to allow
writing of custom files into the HOME directory, and the isolation of the
environment variables that juju cares about.

Perhaps we should split and isolate more.

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:162: api server.
On 2014/05/08 05:34:49, fwereade wrote:
> The JujuConnSuite is all fucked up, and should be used when you just don't
care
> about having coherent context available, you just kinda want everything and
> don't want to think too hard. State server? Client? Both? Whooo! Who cares!
> 
> Yeah, we should fix this; but in the meantime I want people to know it's at
> least somewhat bad/wrong, because then *maybe* someone will take it upon
> themselves to extract a saner subset of the functionality and start using
that;
> as it is it's all too easy to just allow the rot to gently spread without even
> knowing that's what you're doing.

Added a note to indicate that we aren't happy with it as it stands :-)

https://codereview.appspot.com/96110043/diff/1/doc/how-to-write-tests.txt#new...
doc/how-to-write-tests.txt:215: // of the test.
On 2014/05/08 05:34:49, fwereade wrote:
> Really, FWIW, I think we should always be clearing the env at the very start
of
> a test.

Is there not some part of the environment that we actually care about?

Pretty sure some expect bash.