19 TestResource comment:'Normally a test will set up all the objects it needs and tear them down again after it has run.  This self-containedness makes a test more robust.  Use TestResources only for objects that are needed by several tests and that are too ''expensive'' (in time or otherwise) to recreate and destroy for each test.  A viable approach is to develop the code in MyTestCase''s #setUp and #tearDown methods, then at some point refactor the code into the #setUp and #tearDown of a TestResource whose class is added to MyTestCase class>>resource method.

    19 !TestResource class methodsFor:'documentation'!

    20 

    20 

    21 TestResource uses the singleton pattern.  A TestResource class will set up a single instance of itself when first requested and tear it down again at the end of TestSuite>>run (or TestCase>>run, >>debug and >>debugAsFailure).  Normally, a TestResource, once setUp, remains active during the running of all remaining tests and is #reset after all tests have run.  For an exception, see subclass CompetingResource in SUnitResourcePatterns.  Users can choose to #reset a resource in the #tearDown of a test that alters it, sacrificing the performance gain of having a single #setUp of the resource for the certainty that other tests using it will not see the alterations.  Generally however, this should be the exception:  if you need to reset the resource for every test that uses it, its code should just be part of your test''s #setUp and #tearDown code.

    21 documentation

    22 "

    23 Normally a test will set up all the objects it needs and tear them down again after it has run.  

    24 This self-containedness makes a test more robust.  

    25 Use TestResources only for objects that are needed by several tests and that are too 'expensive' 

    26 (in time or otherwise) to recreate and destroy for each test.  

    27 

    28 A viable approach is to develop the code in MyTestCase's #setUp and #tearDown methods, 

    29 then at some point refactor the code into the #setUp and #tearDown of a TestResource 

    30 whose class is added to MyTestCase class>>resource method.

    31 

    32 TestResource uses the singleton pattern.  

    33 A TestResource class will set up a single instance of itself when first requested and tear it down again 

    34 at the end of TestSuite>>run (or TestCase>>run, >>debug and >>debugAsFailure).  

    35 Normally, a TestResource, once setUp, remains active during the running of all remaining tests 

    36 and is #reset after all tests have run.  

    37 

    38 For an exception, see subclass CompetingResource in SUnitResourcePatterns.  

    39 Users can choose to #reset a resource in the #tearDown of a test that alters it, 

    40 sacrificing the performance gain of having a single #setUp of the resource for the certainty 

    41 that other tests using it will not see the alterations.  

    42 

    43 Generally however, this should be the exception:  

    44 if you need to reset the resource for every test that uses it, 

    45 its code should just be part of your test's #setUp and #tearDown code.

    24 	- TestCase class>>resources, to return a collection including the TestResource class, for all test case classes that need it

    48         - TestCase class>>resources, to return a collection including the TestResource class, 

    25 		* a TestCase'' resources are set up in the order returned and torn down in the reverse order

    49           for all test case classes that need it

    26 	- TestResource class>>resources, if the resource itself always needs some other resource to be present before it can set up

    50                 * a TestCase' resources are set up in the order returned and torn down in the reverse order

    27 		* a TestResource''s resource are set up before it and torn down after it, and are set up in the order returned and torn down in the reverse order

    51         - TestResource class>>resources, if the resource itself always needs some other resource 

    28 	- TestResource>>setUp and tearDown, to define initial and final behaviour (just like a test)

    52           to be present before it can set up

    29 	- TestResource>>isAvailable, to return true if it is and false if it isn''t (the framework calls this after setUp);  ideally, this call should not change the resource'' state - that should be done in setUp

    53                 * a TestResource's resource are set up before it and torn down after it, and are set up in the order returned and torn down in the reverse order

    30 

    54         - TestResource>>setUp and tearDown, to define initial and final behaviour (just like a test)

    31 TestResource implements the singleton pattern in its class-side #isAvailable and #reset methods.  Do not override these when creating specific resources;  unless you are developing a whole new pattern of use, it will always be correct to override instance-side #setUp, #tearDown and #isAvailable, and dangerous to override class>>isAvailable, class>>isAlreadyAvailable and class>>reset.

    55         - TestResource>>isAvailable, to return true if it is and false if it isn't 

    32 

    56           (the framework calls this after setUp);  ideally, this call should not change the resource' state 

    33 Generally, users do not code interactions with a test''s resources during the running of a test.  Code that reads a resource'' values while leaving its state strictly alone is safe enough.  A test must leave a resource in a clean state:  always use #reset if a test must protect later-running tests from unsafe changes (and review whether in such a case a resource is the right thing to use in the first place).

    57            - that should be done in setUp

    34 

    58 

    35 See my superclass'' comment for assertion and logging information.

    59 TestResource implements the singleton pattern in its class-side #isAvailable and #reset methods.  

    36 '

    60 Do not override these when creating specific resources;  unless you are developing a whole new pattern of use, 

    37 !

    61 it will always be correct to override instance-side #setUp, #tearDown and #isAvailable, 

    38 

    62 and dangerous to override class>>isAvailable, class>>isAlreadyAvailable and class>>reset.

    63 

    64 Generally, users do not code interactions with a test's resources during the running of a test.  

    65 Code that reads a resource' values while leaving its state strictly alone is safe enough.  

    66 A test must leave a resource in a clean state:  always use #reset if a test must protect 

    67 later-running tests from unsafe changes (and review whether in such a case a resource 

    68 is the right thing to use in the first place).

    69 

    70 See my superclass' comment for assertion and logging information.

    71 "

    72 ! !