Improve formatting for test annotations in reference manual

2016-06-09 17:03:44 +02:00
parent 53909a5333
commit f0451294de
1 changed files with 138 additions and 303 deletions
--- a/src/asciidoc/testing.adoc
+++ b/src/asciidoc/testing.adoc
@@ -331,24 +331,17 @@ you can use in your unit and integration tests in conjunction with the TestConte
 framework. Refer to the corresponding javadocs for further information, including
 default attribute values, attribute aliases, and so on.
-* `@ContextConfiguration`
+===== @ContextConfiguration
-
+`@ContextConfiguration` defines class-level metadata that is used to determine how to
-+
+load and configure an `ApplicationContext` for integration tests. Specifically,
-
+`@ContextConfiguration` declares the application context resource `locations` or the
-Defines class-level metadata that is used to determine how to load and configure an
+annotated `classes` that will be used to load the context.
 `ApplicationContext` for integration tests. Specifically, `@ContextConfiguration`
 declares the application context resource `locations` or the annotated `classes`
 that will be used to load the context.
 +
 Resource locations are typically XML configuration files or Groovy scripts located in
 the classpath; whereas, annotated classes are typically `@Configuration` classes. However,
 resource locations can also refer to files and scripts in the file system, and annotated
 classes can be component classes, etc.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -358,8 +351,6 @@ classes can be component classes, etc.
 	}
 ----
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -369,13 +360,9 @@ classes can be component classes, etc.
 	}
 ----
 +
 As an alternative or in addition to declaring resource locations or annotated classes,
 `@ContextConfiguration` may be used to declare `ApplicationContextInitializer` classes.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -385,15 +372,11 @@ As an alternative or in addition to declaring resource locations or annotated cl
 	}
 ----
 +
 `@ContextConfiguration` may optionally be used to declare the `ContextLoader` strategy
 as well. Note, however, that you typically do not need to explicitly configure the
 loader since the default loader supports either resource `locations` or annotated
 `classes` as well as `initializers`.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -403,8 +386,6 @@ loader since the default loader supports either resource `locations` or annotate
 	}
 ----
 +
 [NOTE]
 ====
 `@ContextConfiguration` provides support for __inheriting__ resource locations or
@@ -412,24 +393,18 @@ configuration classes as well as context initializers declared by superclasses b
 default.
 ====
 +
 See <<testcontext-ctx-management>> and the `@ContextConfiguration` javadocs for
 further details.
-* `@WebAppConfiguration`
+===== @WebAppConfiguration
-
+`@WebAppConfiguration` is a class-level annotation that is used to declare that the
-+
+`ApplicationContext` loaded for an integration test should be a `WebApplicationContext`.
-
+The mere presence of `@WebAppConfiguration` on a test class ensures that a
-A class-level annotation that is used to declare that the `ApplicationContext` loaded
+`WebApplicationContext` will be loaded for the test, using the default value of
-for an integration test should be a `WebApplicationContext`. The mere presence of
+`"file:src/main/webapp"` for the path to the root of the web application (i.e., the
-`@WebAppConfiguration` on a test class ensures that a `WebApplicationContext` will be
+__resource base path__). The resource base path is used behind the scenes to create a
-loaded for the test, using the default value of `"file:src/main/webapp"` for the path to
+`MockServletContext` which serves as the `ServletContext` for the test's
-the root of the web application (i.e., the __resource base path__). The resource base
+`WebApplicationContext`.
 path is used behind the scenes to create a `MockServletContext` which serves as the
 `ServletContext` for the test's `WebApplicationContext`.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -441,14 +416,10 @@ path is used behind the scenes to create a `MockServletContext` which serves as
 	}
 ----
 +
 To override the default, specify a different base resource path via the __implicit__
 `value` attribute. Both `classpath:` and `file:` resource prefixes are supported. If no
 resource prefix is supplied the path is assumed to be a file system resource.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -459,26 +430,17 @@ resource prefix is supplied the path is assumed to be a file system resource.
 	}
 ----
 +
 Note that `@WebAppConfiguration` must be used in conjunction with
 `@ContextConfiguration`, either within a single test class or within a test class
 hierarchy. See the `@WebAppConfiguration` javadocs for further details.
-+
+===== @ContextHierarchy
-
+`@ContextHierarchy` is a class-level annotation that is used to define a hierarchy of
-* `@ContextHierarchy`
++ApplicationContext++s for integration tests. `@ContextHierarchy` should be declared
-
+with a list of one or more `@ContextConfiguration` instances, each of which defines a
-+
+level in the context hierarchy. The following examples demonstrate the use of
-
+`@ContextHierarchy` within a single test class; however, `@ContextHierarchy` can also be
-A class-level annotation that is used to define a hierarchy of ++ApplicationContext++s
+used within a test class hierarchy.
 for integration tests. `@ContextHierarchy` should be declared with a list of one or more
 `@ContextConfiguration` instances, each of which defines a level in the context
 hierarchy. The following examples demonstrate the use of `@ContextHierarchy` within a
 single test class; however, `@ContextHierarchy` can also be used within a test class
 hierarchy.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -492,8 +454,6 @@ hierarchy.
 	}
 ----
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -507,8 +467,6 @@ hierarchy.
 	}
 ----
 +
 If you need to merge or override the configuration for a given level of the context
 hierarchy within a test class hierarchy, you must explicitly name that level by
 supplying the same value to the `name` attribute in `@ContextConfiguration` at each
@@ -516,14 +474,10 @@ corresponding level in the class hierarchy. See
 <<testcontext-ctx-management-ctx-hierarchies>> and the `@ContextHierarchy` javadocs
 for further examples.
-* `@ActiveProfiles`
+===== @ActiveProfiles
-
+`@ActiveProfiles` is a class-level annotation that is used to declare which __bean
-+
+definition profiles__ should be active when loading an `ApplicationContext` for an
-
+integration test.
 A class-level annotation that is used to declare which __bean definition profiles__
 should be active when loading an `ApplicationContext` for test classes.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -535,8 +489,6 @@ should be active when loading an `ApplicationContext` for test classes.
 	}
 ----
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -547,8 +499,6 @@ should be active when loading an `ApplicationContext` for test classes.
 	}
 ----
 +
 [NOTE]
 ====
 `@ActiveProfiles` provides support for __inheriting__ active bean definition profiles
@@ -558,20 +508,13 @@ definition profiles programmatically by implementing a custom
 and registering it via the `resolver` attribute of `@ActiveProfiles`.
 ====
 +
 See <<testcontext-ctx-management-env-profiles>> and the `@ActiveProfiles` javadocs
 for examples and further details.
-* `@TestPropertySource`
+===== @TestPropertySource
-
+`@TestPropertySource` is a class-level annotation that is used to configure the locations
-+
+of properties files and inlined properties to be added to the set of `PropertySources` in
-
+the `Environment` for an `ApplicationContext` loaded for an integration test.
 A class-level annotation that is used to configure the locations of properties files and
 inlined properties to be added to the set of `PropertySources` in the `Environment` for
 an `ApplicationContext` loaded for an integration test.
 + 
 Test property sources have higher precedence than those loaded from the operating
 system's environment or Java system properties as well as property sources added by the
@@ -580,12 +523,8 @@ sources can be used to selectively override properties defined in system and app
 property sources. Furthermore, inlined properties have higher precedence than properties
 loaded from resource locations.
 +
 The following example demonstrates how to declare a properties file from the classpath.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -596,12 +535,8 @@ The following example demonstrates how to declare a properties file from the cla
 	}
 ----
 +
 The following example demonstrates how to declare _inlined_ properties.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -612,32 +547,23 @@ The following example demonstrates how to declare _inlined_ properties.
 	}
 ----
-* `@DirtiesContext`
+===== @DirtiesContext
-
+`@DirtiesContext` indicates that the underlying Spring `ApplicationContext` has been
-+
+__dirtied__ during the execution of a test (i.e., modified or corrupted in some manner --
-
+for example, by changing the state of a singleton bean) and should be closed. When an
-Indicates that the underlying Spring `ApplicationContext` has been __dirtied__ during
+application context is marked __dirty__, it is removed from the testing framework's cache
-the execution of a test (i.e., modified or corrupted in some manner -- for example, by
+and closed. As a consequence, the underlying Spring container will be rebuilt for any
 changing the state of a singleton bean) and should be closed. When an application
 context is marked __dirty__, it is removed from the testing framework's cache and
 closed. As a consequence, the underlying Spring container will be rebuilt for any
 subsequent test that requires a context with the same configuration metadata.
 +
 `@DirtiesContext` can be used as both a class-level and method-level annotation within
 the same class or class hierarchy. In such scenarios, the `ApplicationContext` is marked
 as __dirty__ before or after any such annotated method as well as before or after the
 current test class, depending on the configured `methodMode` and `classMode`.
 +
 The following examples explain when the context would be dirtied for various
 configuration scenarios:
-+
+* Before the current test class, when declared on a class with class mode set to
 ** Before the current test class, when declared on a class with class mode set to
 `BEFORE_CLASS`.
 +
@@ -653,7 +579,7 @@ configuration scenarios:
 +
-** After the current test class, when declared on a class with class mode set to
+* After the current test class, when declared on a class with class mode set to
 `AFTER_CLASS` (i.e., the default class mode).
 +
@@ -669,7 +595,7 @@ configuration scenarios:
 +
-** Before each test method in the current test class, when declared on a class with class
+* Before each test method in the current test class, when declared on a class with class
 mode set to `BEFORE_EACH_TEST_METHOD.`
 +
@@ -685,7 +611,7 @@ mode set to `BEFORE_EACH_TEST_METHOD.`
 +
-** After each test method in the current test class, when declared on a class with class
+* After each test method in the current test class, when declared on a class with class
 mode set to `AFTER_EACH_TEST_METHOD.`
 +
@@ -701,7 +627,7 @@ mode set to `AFTER_EACH_TEST_METHOD.`
 +
-** Before the current test, when declared on a method with the method mode set to
+* Before the current test, when declared on a method with the method mode set to
 `BEFORE_METHOD`.
 +
@@ -718,7 +644,7 @@ mode set to `AFTER_EACH_TEST_METHOD.`
 +
-** After the current test, when declared on a method with the method mode set to
+* After the current test, when declared on a method with the method mode set to
 `AFTER_METHOD` (i.e., the default method mode).
 +
@@ -733,8 +659,6 @@ mode set to `AFTER_EACH_TEST_METHOD.`
 	}
 ----
 +
 If `@DirtiesContext` is used in a test whose context is configured as part of a context
 hierarchy via `@ContextHierarchy`, the `hierarchyMode` flag can be used to control how
 the context cache is cleared. By default an __exhaustive__ algorithm will be used that
@@ -745,8 +669,6 @@ will be removed from the context cache and closed. If the __exhaustive__ algorit
 overkill for a particular use case, the simpler __current level__ algorithm can be
 specified instead, as seen below.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -768,20 +690,14 @@ specified instead, as seen below.
 	}
 ----
 +
 For further details regarding the `EXHAUSTIVE` and `CURRENT_LEVEL` algorithms see the
 `DirtiesContext.HierarchyMode` javadocs.
-* `@TestExecutionListeners`
+===== @TestExecutionListeners
-
+`@TestExecutionListeners` defines class-level metadata for configuring the
-+
+`TestExecutionListener` implementations that should be registered with the
-
+`TestContextManager`. Typically, `@TestExecutionListeners` is used in conjunction with
-Defines class-level metadata for configuring which ++TestExecutionListener++s should be
+`@ContextConfiguration`.
 registered with the `TestContextManager`. Typically, `@TestExecutionListeners` is used
 in conjunction with `@ContextConfiguration`.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -793,23 +709,15 @@ in conjunction with `@ContextConfiguration`.
 	}
 ----
-+
+`@TestExecutionListeners` supports _inherited_ listeners by default. See the javadocs
 `@TestExecutionListeners` supports __inherited__ listeners by default. See the javadocs
 for an example and further details.
-+
+===== @Commit
-
+`@Commit` indicates that the transaction for a transactional test method should be
-* `@Commit`
+__committed__ after the test method has completed. `@Commit` can be used as a direct
-
+replacement for `@Rollback(false)` in order to more explicitly convey the intent of the
-+
+code. Analogous to `@Rollback`, `@Commit` may also be declared as a class-level or
-
+method-level annotation.
 Indicates that the transaction for a transactional test method should be __committed__
 after the test method has completed. `@Commit` can be used as a direct replacement for
 `@Rollback(false)` in order to more explicitly convey the intent of the code. Analogous to
 `@Rollback`, `@Commit` may also be declared as a class-level or method-level annotation.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -821,25 +729,18 @@ after the test method has completed. `@Commit` can be used as a direct replaceme
 	}
 ----
-* `@Rollback`
+===== @Rollback
-
+`@Rollback` indicates whether the transaction for a transactional test method should be
-+
+__rolled back__ after the test method has completed. If `true`, the transaction is rolled
-
+back; otherwise, the transaction is committed (see also `@Commit`). Rollback semantics
-Indicates whether the transaction for a transactional test method should be __rolled
+for integration tests in the Spring TestContext Framework default to `true` even if
 back__ after the test method has completed. If `true`, the transaction is rolled back;
 otherwise, the transaction is committed (see also `@Commit`). Rollback semantics for
 integration tests in the Spring TestContext Framework default to `true` even if
 `@Rollback` is not explicitly declared.
 +
 When declared as a class-level annotation, `@Rollback` defines the default rollback
 semantics for all test methods within the test class hierarchy. When declared as a
 method-level annotation, `@Rollback` defines rollback semantics for the specific test
 method, potentially overriding class-level `@Rollback` or `@Commit` semantics.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -850,18 +751,12 @@ method, potentially overriding class-level `@Rollback` or `@Commit` semantics.
 	}
 ----
-* `@BeforeTransaction`
+===== @BeforeTransaction
-
+`@BeforeTransaction` indicates that the annotated `void` method should be executed
-+
+__before__ a transaction is started for test methods configured to run within a
-
+transaction via Spring's `@Transactional` annotation. As of Spring Framework 4.3,
-Indicates that the annotated `void` method should be executed __before__ a transaction
+`@BeforeTransaction` methods are not required to be `public` and may be declared on Java
-is started for test methods configured to run within a transaction via Spring's
+8 based interface default methods.
 `@Transactional` annotation. As of Spring Framework 4.3, `@BeforeTransaction` methods
 are not required to be `public` and may be declared on Java 8 based interface default
 methods.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -872,17 +767,12 @@ methods.
 	}
 ----
-* `@AfterTransaction`
+===== @AfterTransaction
-
+`@AfterTransaction` indicates that the annotated `void` method should be executed
-+
+__after__ a transaction is ended for test methods configured to run within a transaction
-
+via Spring's `@Transactional` annotation. As of Spring Framework 4.3, `@AfterTransaction`
-Indicates that the annotated `void` method should be executed __after__ a transaction
+methods are not required to be `public` and may be declared on Java 8 based interface
-is ended for test methods configured to run within a transaction via Spring's
+default methods.
 `@Transactional` annotation. As of Spring Framework 4.3, `@AfterTransaction` methods
 are not required to be `public` and may be declared on Java 8 based interface default
 methods.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -893,14 +783,9 @@ methods.
 	}
 ----
-* `@Sql`
+===== @Sql
-
+`@Sql` is used to annotate a test class or test method to configure SQL scripts to be
-+
+executed against a given database during integration tests.
 Used to annotate a test class or test method to configure SQL scripts to be executed
 against a given database during integration tests.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -912,18 +797,11 @@ against a given database during integration tests.
 	}
 ----
 +
 See <<testcontext-executing-sql-declaratively>> for further details.
-* `@SqlConfig`
+===== @SqlConfig
-
+`@SqlConfig` defines metadata that is used to determine how to parse and execute SQL
-+
+scripts configured via the `@Sql` annotation.
 Defines metadata that is used to determine how to parse and execute SQL scripts
 configured via the `@Sql` annotation.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -938,16 +816,12 @@ configured via the `@Sql` annotation.
 	}
 ----
-* `@SqlGroup`
+===== @SqlGroup
-
+`@SqlGroup` is a container annotation that aggregates several `@Sql` annotations.
-+
+`@SqlGroup` can be used natively, declaring several nested `@Sql` annotations, or it can
-
+be used in conjunction with Java 8's support for repeatable annotations, where `@Sql` can
-A container annotation that aggregates several `@Sql` annotations. Can be used natively,
+simply be declared several times on the same class or method, implicitly generating this
-declaring several nested `@Sql` annotations. Can also be used in conjunction with Java
+container annotation.
 8's support for repeatable annotations, where `@Sql` can simply be declared several times
 on the same class or method, implicitly generating this container annotation.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -1002,15 +876,11 @@ The following annotations are __only__ supported when used in conjunction with t
 <<testcontext-junit4-runner,SpringRunner>>, <<testcontext-junit4-rules,Spring's JUnit
 rules>>, or <<testcontext-support-classes-junit4,Spring's JUnit 4 support classes>>.
-* `@IfProfileValue`
+===== @IfProfileValue
-
+`@IfProfileValue` indicates that the annotated test is enabled for a specific testing
-+
+environment. If the configured `ProfileValueSource` returns a matching `value` for the
-
+provided `name`, the test is enabled. Otherwise, the test will be disabled and
-Indicates that the annotated test is enabled for a specific testing environment. If the
+effectively _ignored_.
 configured `ProfileValueSource` returns a matching `value` for the provided `name`, the
 test is enabled. Otherwise, the test will be disabled and effectively _ignored_.
 +
 `@IfProfileValue` can be applied at the class level, the method level, or both.
 Class-level usage of `@IfProfileValue` takes precedence over method-level usage for any
@@ -1020,8 +890,6 @@ enabled both at the class level _and_ at the method level; the absence of
 semantics of JUnit 4's `@Ignore` annotation, except that the presence of `@Ignore` always
 disables a test.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -1032,14 +900,10 @@ disables a test.
 	}
 ----
 +
 Alternatively, you can configure `@IfProfileValue` with a list of `values` (with __OR__
 semantics) to achieve TestNG-like support for __test groups__ in a JUnit 4 environment.
 Consider the following example:
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -1050,18 +914,11 @@ Consider the following example:
 	}
 ----
-+
+===== @ProfileValueSourceConfiguration
-
+`@ProfileValueSourceConfiguration` is a class-level annotation that specifies what type
-* `@ProfileValueSourceConfiguration`
+of `ProfileValueSource` to use when retrieving __profile values__ configured through the
-
+`@IfProfileValue` annotation. If `@ProfileValueSourceConfiguration` is not declared for a
-+
+test, `SystemProfileValueSource` is used by default.
 Class-level annotation that specifies what type of `ProfileValueSource` to use when
 retrieving __profile values__ configured through the `@IfProfileValue` annotation. If
 `@ProfileValueSourceConfiguration` is not declared for a test,
 `SystemProfileValueSource` is used by default.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -1072,21 +929,14 @@ retrieving __profile values__ configured through the `@IfProfileValue` annotatio
 	}
 ----
-* `@Timed`
+===== @Timed
-
+`@Timed` indicates that the annotated test method must finish execution in a specified
-+
+time period (in milliseconds). If the text execution time exceeds the specified time
-
+period, the test fails.
 Indicates that the annotated test method must finish execution in a specified time
 period (in milliseconds). If the text execution time exceeds the specified time period,
 the test fails.
 +
 The time period includes execution of the test method itself, any repetitions of the
 test (see `@Repeat`), as well as any __set up__ or __tear down__ of the test fixture.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -1096,8 +946,6 @@ test (see `@Repeat`), as well as any __set up__ or __tear down__ of the test fix
 	}
 ----
 +
 Spring's `@Timed` annotation has different semantics than JUnit 4's `@Test(timeout=...)`
 support. Specifically, due to the manner in which JUnit 4 handles test execution timeouts
 (that is, by executing the test method in a separate `Thread`), `@Test(timeout=...)`
@@ -1105,20 +953,13 @@ preemptively fails the test if the test takes too long. Spring's `@Timed`, on th
 hand, does not preemptively fail the test but rather waits for the test to complete
 before failing.
-* `@Repeat`
+===== @Repeat
-
+`@Repeat` indicates that the annotated test method must be executed repeatedly. The
-+
+number of times that the test method is to be executed is specified in the annotation.
 Indicates that the annotated test method must be executed repeatedly. The number of
 times that the test method is to be executed is specified in the annotation.
 +
 The scope of execution to be repeated includes execution of the test method itself as
 well as any __set up__ or __tear down__ of the test fixture.
 +
 [source,java,indent=0]
 [subs="verbatim,quotes"]
 ----
@@ -1132,9 +973,9 @@ well as any __set up__ or __tear down__ of the test fixture.
 [[integration-testing-annotations-meta]]
 ==== Meta-Annotation Support for Testing
-Since Spring Framework 4.0, it is possible to use test-related annotations as
+It is possible to use most test-related annotations as
-<<beans-meta-annotations,meta-annotations>> in order to create custom _composed annotations_
+<<beans-meta-annotations,meta-annotations>> in order to create custom _composed
-and reduce configuration duplication across a test suite.
+annotations_ and reduce configuration duplication across a test suite.
 Each of the following may be used as meta-annotations in conjunction with the
 <<testcontext-framework,TestContext framework>>.
@@ -1248,76 +1089,70 @@ is responsible for loading an `ApplicationContext` for a given test class. Consu
 javadocs and the Spring test suite for further information and examples of various
 implementations.
-* `TestContext`: Encapsulates the context in which a test is executed, agnostic of the
+===== TestContext
-  actual testing framework in use, and provides context management and caching support
+`TestContext` encapsulates the context in which a test is executed, agnostic of the
-  for the test instance for which it is responsible. The `TestContext` also delegates to a
+actual testing framework in use, and provides context management and caching support for
-  `SmartContextLoader` to load an `ApplicationContext` if requested.
+the test instance for which it is responsible. The `TestContext` also delegates to a
-* `TestContextManager`: The main entry point into the __Spring TestContext Framework__,
+`SmartContextLoader` to load an `ApplicationContext` if requested.
  which manages a single `TestContext` and signals events to each registered
  `TestExecutionListener` at well-defined test execution points:
 ** prior to any __before class__ or __before all__ methods of a particular testing framework
 ** test instance post-processing
 ** prior to any __before__ or __before each__ methods of a particular testing framework
 ** after any __after__ or __after each__ methods of a particular testing framework
 ** after any __after class__ or __after all__ methods of a particular testing framework
 * `TestExecutionListener`: Defines the API for reacting to test execution
  events published by the `TestContextManager` with which the listener is registered. See
  <<testcontext-tel-config>>.
 * `ContextLoader`: Strategy interface introduced in Spring 2.5 for loading an
  `ApplicationContext` for an integration test managed by the Spring TestContext
  Framework.
-+
+===== TestContextManager
 `TestContextManager` is the main entry point into the __Spring TestContext Framework__,
 which manages a single `TestContext` and signals events to each registered
 `TestExecutionListener` at well-defined test execution points:
 * prior to any __before class__ or __before all__ methods of a particular testing framework
 * test instance post-processing
 * prior to any __before__ or __before each__ methods of a particular testing framework
 * after any __after__ or __after each__ methods of a particular testing framework
 * after any __after class__ or __after all__ methods of a particular testing framework
 ===== TestExecutionListener
 `TestExecutionListener` defines the API for reacting to test execution events published
 by the `TestContextManager` with which the listener is registered. See
 <<testcontext-tel-config>>.
 ===== Context Loaders
 `ContextLoader` is a strategy interface that was introduced in Spring 2.5 for loading an
 `ApplicationContext` for an integration test managed by the Spring TestContext Framework.
 Implement `SmartContextLoader` instead of this interface in order to provide support for
 annotated classes, active bean definition profiles, test property sources, context
 hierarchies, and `WebApplicationContext` support.
-* `SmartContextLoader`: Extension of the `ContextLoader` interface introduced in Spring
+`SmartContextLoader` is an extension of the `ContextLoader` interface introduced in
-  3.1.
+Spring 3.1. The `SmartContextLoader` SPI supersedes the `ContextLoader` SPI that was
-
+introduced in Spring 2.5. Specifically, a `SmartContextLoader` can choose to process
-+
+resource `locations`, annotated `classes`, or context `initializers`. Furthermore, a
 The `SmartContextLoader` SPI supersedes the `ContextLoader` SPI that was introduced in
 Spring 2.5. Specifically, a `SmartContextLoader` can choose to process resource
 `locations`, annotated `classes`, or context `initializers`. Furthermore, a
 `SmartContextLoader` can set active bean definition profiles and test property sources in
 the context that it loads.
 +
 Spring provides the following implementations:
-+
+* `DelegatingSmartContextLoader`: one of two default loaders which delegates internally
 ** `DelegatingSmartContextLoader`: one of two default loaders which delegates internally
 to an `AnnotationConfigContextLoader`, a `GenericXmlContextLoader`, or a
 `GenericGroovyXmlContextLoader` depending either on the configuration declared for the
 test class or on the presence of default locations or default configuration classes.
 Groovy support is only enabled if Groovy is on the classpath.
-** `WebDelegatingSmartContextLoader`: one of two default loaders which delegates
+* `WebDelegatingSmartContextLoader`: one of two default loaders which delegates
 internally to an `AnnotationConfigWebContextLoader`, a `GenericXmlWebContextLoader`, or a
 `GenericGroovyXmlWebContextLoader` depending either on the configuration declared for the
 test class or on the presence of default locations or default configuration classes. A
 web `ContextLoader` will only be used if `@WebAppConfiguration` is present on the test
 class. Groovy support is only enabled if Groovy is on the classpath.
-** `AnnotationConfigContextLoader`: loads a standard `ApplicationContext` from
+* `AnnotationConfigContextLoader`: loads a standard `ApplicationContext` from
 __annotated classes__.
-** `AnnotationConfigWebContextLoader`: loads a `WebApplicationContext` from __annotated
+* `AnnotationConfigWebContextLoader`: loads a `WebApplicationContext` from __annotated
 classes__.
-** `GenericGroovyXmlContextLoader`: loads a standard `ApplicationContext` from __resource
+* `GenericGroovyXmlContextLoader`: loads a standard `ApplicationContext` from __resource
 locations__ that are either Groovy scripts or XML configuration files.
-** `GenericGroovyXmlWebContextLoader`: loads a `WebApplicationContext` from __resource
+* `GenericGroovyXmlWebContextLoader`: loads a `WebApplicationContext` from __resource
 locations__ that are either Groovy scripts or XML configuration files.
-** `GenericXmlContextLoader`: loads a standard `ApplicationContext` from XML __resource
+* `GenericXmlContextLoader`: loads a standard `ApplicationContext` from XML __resource
 locations__.
-** `GenericXmlWebContextLoader`: loads a `WebApplicationContext` from XML __resource
+* `GenericXmlWebContextLoader`: loads a `WebApplicationContext` from XML __resource
 locations__.
-** `GenericPropertiesContextLoader`: loads a standard `ApplicationContext` from Java
+* `GenericPropertiesContextLoader`: loads a standard `ApplicationContext` from Java
 Properties files.
 The following sections explain how to configure the TestContext framework and provide
 working examples of how to write unit and integration tests with the framework.
 [[testcontext-tel-config]]
 ==== TestExecutionListener configuration