Added documentation for testing

Resources/doc/index.rst

@@ -17,6 +17,7 @@ Reference Guide
    reference/advanced_usage
    reference/cache
    reference/events
+   reference/testing
 
 Cookbooks
 ---------

Resources/doc/reference/testing.rst

@@ -0,0 +1,68 @@
+.. index::
+    double: Test Widgets; Definition
+
+Testing
+=======
+
+Test Blocks
+~~~~~~~~~~~
+
+Given the following block service:
+
+.. code-block:: php
+
+    class CustomBlockService extends AbstractBlockService
+    {
+        public function execute(BlockContextInterface $blockContext, Response $response = null)
+        {
+            return $this->renderResponse($blockContext->getTemplate(), array(
+                'context' => $blockContext,
+                'block' => $blockContext->getBlock(),
+                'settings' => $blockContext->getSettings(),
+            ), $response);
+        }
+
+        public function configureSettings(OptionsResolver $resolver)
+        {
+            $resolver->setDefaults(array(
+                'foo' => 'bar',
+                'attr' => array(),
+                'template' => false,
+            ));
+        }
+    }
+
+
+You can write unit tests for block services with the following code.
+
+.. code-block:: php
+
+    use Sonata\BlockBundle\Test\AbstractBlockServiceTestCase;
+
+    class CustomBlockServiceTest extends AbstractBlockServiceTestCase
+    {
+        public function testDefaultSettings()
+        {
+            $blockService = new CustomBlockService('foo', $this->templating);
+            $blockContext = $this->getBlockContext($blockService);
+
+            $this->assertSettings(array(
+                'foo' => bar,
+                'attr' => array(),
+                'template' => false,
+            ), $blockContext);
+        }
+
+        public function testExecute()
+        {
+            $blockService = new CustomBlockService('foo', $this->templating);
+            $blockContext = $this->getBlockContext($blockService);
+
+            $service->execute($blockContext);
+
+            $this->assertSame($blockContext, $this->templating->parameters['context']);
+            $this->assertInternalType('array', $this->templating->parameters['settings']);
+            $this->assertInstanceOf('Sonata\BlockBundle\Model\BlockInterface', $this->templating->parameters['block']);
+            $this->assertSame('bar', $this->templating->parameters['foo']);
+        }
+    }

Test/AbstractBlockServiceTestCase.php

@@ -55,6 +55,13 @@ protected function setUp()
         $this->blockContextManager = new BlockContextManager($blockLoader, $this->blockServiceManager);
     }
 
+    /**
+     * Create a mocked block service.
+     *
+     * @param BlockServiceInterface $blockService A block service
+     *
+     * @return BlockContextInterface
+     */
     protected function getBlockContext(BlockServiceInterface $blockService)
     {
         $this->blockServiceManager->expects($this->once())->method('get')->will($this->returnValue($blockService));
@@ -68,6 +75,12 @@ protected function getBlockContext(BlockServiceInterface $blockService)
         return $blockContext;
     }
 
+    /**
+     * Asserts that the block settings have the expected values.
+     *
+     * @param array                 $expected     Expected settings
+     * @param BlockContextInterface $blockContext BlockContext object
+     */
     protected function assertSettings(array $expected, BlockContextInterface $blockContext)
     {
         $completeExpectedOptions = array_merge(array(