docs: add user guide

Author: kenjis

user_guide_src/source/changelogs/v4.3.0.rst

@@ -33,7 +33,8 @@ Others
 Enhancements
 ************
 
-- Added the ``StreamFilterTrait`` to make it easier to work with capturing data from STDOUT and STDERR streams. See :ref:`testing-overview-stream-filters`.
+- Added the ``StreamFilterTrait`` to make it easier to work with capturing data from STDOUT and STDERR streams. See :ref:`testing-cli-output`.
+- Added the ``PhpStreamWrapper`` to make it easier to work with setting data to ``php://stdin``. See :ref:`testing-cli-input`.
 - Added before and after events to ``BaseModel::insertBatch()`` and ``BaseModel::updateBatch()`` methods. See :ref:`model-events-callbacks`.
 - Added ``Model::allowEmptyInserts()`` method to insert empty data. See :ref:`Using CodeIgniter's Model <model-allow-empty-inserts>`
 - Added ``$routes->useSupportedLocalesOnly(true)`` so that the Router returns 404 Not Found if the locale in the URL is not supported in ``Config\App::$supportedLocales``. See :ref:`Localization <localization-in-routes>`

user_guide_src/source/cli/cli_library.rst

@@ -31,6 +31,12 @@ Sometimes you need to ask the user for more information. They might not have pro
 arguments, or the script may have encountered an existing file and needs confirmation before overwriting. This is
 handled with the ``prompt()`` or ``promptByKey()`` method.
 
+.. note:: Since v4.3.0, you can write tests for these methods with ``PhpStreamWrapper``.
+    See :ref:`testing-cli-input`.
+
+prompt()
+========
+
 You can provide a question by passing it in as the first parameter:
 
 .. literalinclude:: cli_library/002.php

user_guide_src/source/testing/overview.rst

@@ -252,10 +252,10 @@ component name:
 
 .. note:: All component Factories are reset by default between each test. Modify your test case's ``$setUpMethods`` if you need instances to persist.
 
-.. _testing-overview-stream-filters:
+.. _testing-cli-output:
 
-Stream Filters
-==============
+Testing CLI Output
+==================
 
 **StreamFilterTrait** provides an alternate to these helper methods.
 
@@ -276,3 +276,23 @@ See :ref:`Testing Traits <testing-overview-traits>`.
 
 If you override the ``setUp()`` or ``tearDown()`` methods in your test, then you must call the ``parent::setUp()`` and
 ``parent::tearDown()`` methods respectively to configure the ``StreamFilterTrait``.
+
+.. _testing-cli-input:
+
+Testing CLI Input
+=================
+
+**PhpStreamWrapper** provides a way to write tests for methods that require user input,
+such as ``CLI::prompt()``, ``CLI::wait()``, and ``CLI::input()``.
+
+**Overview of methods**
+
+- ``PhpStreamWrapper::register()`` Register the ``PhpStreamWrapper`` to php protocol.
+- ``PhpStreamWrapper::restore()`` Restore the php protocol wrapper back to the PHP built-in wrapper.
+- ``PhpStreamWrapper::setContent()`` Set the input data.
+
+An example demonstrating this inside one of your test cases:
+
+.. literalinclude:: overview/019.php
+
+.. note:: It is strongly recommended that ``PhpStreamWrapper`` be registered/unregistered only when needed. Otherwise, it will interfere with other built-in php streams while registered.

user_guide_src/source/testing/overview/019.php

@@ -0,0 +1,25 @@
+<?php
+
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Test\CIUnitTestCase;
+use CodeIgniter\Test\PhpStreamWrapper;
+
+final class SomeTest extends CIUnitTestCase
+{
+    public function testPrompt(): void
+    {
+        // Register the PhpStreamWrapper.
+        PhpStreamWrapper::register();
+
+        // Set the user input to 'red'. It will be provided as `php://stdin` output.
+        $expected = 'red';
+        PhpStreamWrapper::setContent($expected);
+
+        $output = CLI::prompt('What is your favorite color?');
+
+        $this->assertSame($expected, $output);
+
+        // Restore php protocol wrapper.
+        PhpStreamWrapper::restore();
+    }
+}