docs: clarify Session Testing behavior and assertion scope (codeigniter4#9857)

* docs: link to Session Testing

* docs: add session testing

* docs: add all session testing code

* style: run cs-fix

* docs: fix load session config

Author: datamweb

user_guide_src/source/libraries/sessions.rst

@@ -514,7 +514,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 </testing/session_testing>`.
 
 FileHandler Driver (the default)
 ================================

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
 ----------------------
 

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 <overview>
-    Database <database>
-    Generating Data <fabricator>
-    Controller Testing <controllers>
-    HTTP Testing <feature>
-    response
-    cli
-    Mocking <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 <overview>
+    Database <database>
+    Generating Data <fabricator>
+    Controller Testing <controllers>
+    HTTP Testing <feature>
+    response
+    cli
+    Mocking <mocking>
+    benchmark
+    debugging
+    Session Testing <session_testing>

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
 ==================
 

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 <response-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 <feature-setting-session-values>`

user_guide_src/source/testing/session_testing/001.php

@@ -0,0 +1,14 @@
+<?php
+
+use CodeIgniter\Session\Handlers\ArrayHandler;
+use CodeIgniter\Session\Session;
+use Config\Session as SessionConfig;
+
+// Load session config
+$config = config(SessionConfig::class);
+
+// Initialize ArrayHandler with config and optional IP
+$arrayHandler = new ArrayHandler($config, '127.0.0.1');
+
+// Create session instance for testing
+$testSession = new Session($arrayHandler, $config);

user_guide_src/source/testing/session_testing/002.php

@@ -0,0 +1,10 @@
+<?php
+
+// Set session data
+$testSession->set('framework', 'CodeIgniter4');
+
+// Retrieve session data
+echo $testSession->get('framework'); // outputs 'CodeIgniter4'
+
+// Remove session data
+$testSession->remove('framework');

user_guide_src/source/testing/session_testing/003.php

@@ -0,0 +1,38 @@
+<?php
+
+use CodeIgniter\Session\Handlers\ArrayHandler;
+use CodeIgniter\Session\Session;
+use CodeIgniter\Test\CIUnitTestCase;
+use Config\Session as SessionConfig;
+
+class SessionTest extends CIUnitTestCase
+{
+    protected Session $testSession;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        // Load session configuration
+        $config = new SessionConfig();
+
+        // Initialize ArrayHandler with config
+        $arrayHandler = new ArrayHandler($config, '127.0.0.1');
+
+        // Create session instance
+        $this->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'));
+    }
+}

user_guide_src/source/testing/session_testing/004.php

@@ -0,0 +1,16 @@
+<?php
+
+// Set a session value
+$testSession->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'));