diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 03c2bbe81fc2..322c3fd12322 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -507,7 +507,8 @@ Have it in mind though, every driver has different caveats, so be sure to get yourself familiar with them (below) before you make that choice. .. note:: The ArrayHandler is used during testing and stores all data within - a PHP array, while preventing the data from being persisted. + a PHP array, while preventing the data from being persisted. See + :doc:`Testing Sessions `. FileHandler Driver (the default) ================================ diff --git a/user_guide_src/source/testing/feature.rst b/user_guide_src/source/testing/feature.rst index 00100f8a7885..67337fa0464c 100644 --- a/user_guide_src/source/testing/feature.rst +++ b/user_guide_src/source/testing/feature.rst @@ -63,6 +63,8 @@ override any existing routes in the system: Each of the "routes" is a 3 element array containing the HTTP verb (or "add" for all), the URI to match, and the routing destination. +.. _feature-setting-session-values: + Setting Session Values ---------------------- diff --git a/user_guide_src/source/testing/index.rst b/user_guide_src/source/testing/index.rst index b6a71055698c..866ef30f5b6f 100644 --- a/user_guide_src/source/testing/index.rst +++ b/user_guide_src/source/testing/index.rst @@ -1,20 +1,21 @@ -####### -Testing -####### - -CodeIgniter ships with a number of tools to help you test and debug your application thoroughly. -The following sections should get you quickly testing your applications. - -.. toctree:: - :titlesonly: - - Getting Started - Database - Generating Data - Controller Testing - HTTP Testing - response - cli - Mocking - benchmark - debugging +####### +Testing +####### + +CodeIgniter ships with a number of tools to help you test and debug your application thoroughly. +The following sections should get you quickly testing your applications. + +.. toctree:: + :titlesonly: + + Getting Started + Database + Generating Data + Controller Testing + HTTP Testing + response + cli + Mocking + benchmark + debugging + Session Testing diff --git a/user_guide_src/source/testing/response.rst b/user_guide_src/source/testing/response.rst index 552133272a28..419df7620782 100644 --- a/user_guide_src/source/testing/response.rst +++ b/user_guide_src/source/testing/response.rst @@ -100,6 +100,8 @@ Asserts that the HTTP status code returned matches $code. .. literalinclude:: response/010.php :lines: 2- +.. _response-session-assertions: + Session Assertions ================== diff --git a/user_guide_src/source/testing/session_testing.rst b/user_guide_src/source/testing/session_testing.rst new file mode 100644 index 000000000000..17f787454fac --- /dev/null +++ b/user_guide_src/source/testing/session_testing.rst @@ -0,0 +1,68 @@ +############### +Session Testing +############### + +Testing session behavior in your application is made simple with the ArrayHandler session driver. +Unlike other session drivers, ArrayHandler does not persist data to disk, database, or external storage. +This allows you to simulate session interactions safely during unit or integration tests, without affecting real session data. + +Using this driver, you can set, retrieve, and assert session data entirely in memory, making your tests faster and more isolated. +While in most production scenarios you would use file, database, or cache-backed sessions, ArrayHandler exists specifically to support testing workflows and prevent side effects. + +.. contents:: + :local: + :depth: 2 + +Initializing Sessions +===================== + +You can initialize a session using the ArrayHandler driver for testing. This example shows how to create a session instance with a proper configuration: + +.. literalinclude:: session_testing/001.php + +Setting and Retrieving Data +=========================== + +Once initialized, you can set session values and retrieve them as usual: + +.. literalinclude:: session_testing/002.php + +.. note:: + + Session data is stored in memory and lasts as long as the ArrayHandler object exists; + after the object is destroyed (typically at the end of a request or test), the data is lost. + +Example Test Case +================= + +Here's a simple example demonstrating usage of the ArrayHandler in a PHPUnit test: + +.. literalinclude:: session_testing/003.php + +Session Assertions +================== + +Using PHPUnit Assertions with ArrayHandler +------------------------------------------ + +When testing sessions directly with Session and ArrayHandler in a unit test, use standard PHPUnit assertions. +``assertSessionHas()`` and ``assertSessionMissing()`` are not available in this context because you are interacting directly with the session object, +not a response object. + +.. literalinclude:: session_testing/004.php + +Session Assertions via TestResponse +----------------------------------- + +When testing controllers or HTTP responses, you can use CodeIgniter 4’s session +assertion helpers, such as ``assertSessionHas()`` and ``assertSessionMissing()``, +which are available on the ``TestResponse`` object. These helpers allow you to +assert the state of the session during the HTTP request/response lifecycle. +See more: :ref:`Session Assertions ` + +Custom Session Values +===================== + +In Feature Tests, you can provide custom session data for a single test using the ``withSession()`` method. +This allows you to simulate session states such as logged-in users or specific roles during the request. +For full details and examples, see: :ref:`Setting Session Values ` \ No newline at end of file diff --git a/user_guide_src/source/testing/session_testing/001.php b/user_guide_src/source/testing/session_testing/001.php new file mode 100644 index 000000000000..01ad520b7ed0 --- /dev/null +++ b/user_guide_src/source/testing/session_testing/001.php @@ -0,0 +1,14 @@ +set('framework', 'CodeIgniter4'); + +// Retrieve session data +echo $testSession->get('framework'); // outputs 'CodeIgniter4' + +// Remove session data +$testSession->remove('framework'); diff --git a/user_guide_src/source/testing/session_testing/003.php b/user_guide_src/source/testing/session_testing/003.php new file mode 100644 index 000000000000..8a9ecaf64b92 --- /dev/null +++ b/user_guide_src/source/testing/session_testing/003.php @@ -0,0 +1,38 @@ +testSession = new Session($arrayHandler, $config); + } + + public function testFrameworkNameInSession(): void + { + // Set a session value + $this->testSession->set('framework', 'CodeIgniter'); + + // Assert the value exists and is correct + $this->assertSame('CodeIgniter', $this->testSession->get('framework')); + + // Remove the session value + $this->testSession->remove('framework'); + $this->assertNull($this->testSession->get('framework')); + } +} diff --git a/user_guide_src/source/testing/session_testing/004.php b/user_guide_src/source/testing/session_testing/004.php new file mode 100644 index 000000000000..ef7ab12ba472 --- /dev/null +++ b/user_guide_src/source/testing/session_testing/004.php @@ -0,0 +1,16 @@ +set('framework', 'CodeIgniter4'); + +// Assert the state of the session using PHPUnit assertions +$this->assertSame('CodeIgniter4', $testSession->get('framework')); // Value exists + +// Not empty +$this->assertNotEmpty($testSession->get('framework')); + +// Remove the value and assert it's gone +$testSession->remove('framework'); + +// Should be null +$this->assertNull($testSession->get('framework'));