Skip to content

Commit 640d38d

Browse files
committed
docs: add docs
1 parent 8f4eb05 commit 640d38d

File tree

3 files changed

+114
-5
lines changed

3 files changed

+114
-5
lines changed

user_guide_src/source/changelogs/v4.5.0.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ Testing
5555

5656
- **DomParser:** The new methods were added ``seeXPath()`` and ``dontSeeXPath()``
5757
which allows users to work directly with DOMXPath object, using complex expressions.
58+
- **CLI:** The new ``InputOutput`` class was added and now you can write test
59+
for commands more easily if you use ``MockInputOutput``.
60+
See :ref:`using-mock-input-output`.
5861

5962
Database
6063
========

user_guide_src/source/testing/cli.rst

Lines changed: 74 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,73 @@
22
Testing CLI Commands
33
####################
44

5+
.. contents::
6+
:local:
7+
:depth: 3
8+
9+
.. _using-mock-input-output:
10+
11+
*********************
12+
Using MockInputOutput
13+
*********************
14+
15+
.. versionadded:: 4.5.0
16+
17+
MockInputOutput
18+
===============
19+
20+
**MockInputOutput** provides a esay way to write tests for commands that require
21+
user input, such as ``CLI::prompt()``, ``CLI::wait()``, and ``CLI::input()``.
22+
23+
You can replace the ``InputOutput`` class with ``MockInputOutput`` during test
24+
execution to capture inputs and outputs.
25+
26+
.. note:: When you use ``MockInputOutput``, you don't need to use
27+
:ref:`stream-filter-trait`, :ref:`ci-test-stream-filter`, and
28+
:ref:`php-stream-wrapper`.
29+
30+
Helper Methods
31+
---------------
32+
33+
getOutput(?int $index = null): string
34+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
35+
36+
Gets the output.
37+
38+
- If you call it like ``$io->getOutput()``, it returns the whole output string.
39+
- If you specify ``0`` or a positive number, it returns the output array item.
40+
Each item has the output of a ``CLI::fwrite()`` call.
41+
- If you specify a negative number ``-n``, it returns the last ``n``-th item of
42+
the output array.
43+
44+
getOutputs(): array
45+
^^^^^^^^^^^^^^^^^^^
46+
47+
Returns the output array. Each item has the output of a ``CLI::fwrite()`` call.
48+
49+
How to Use
50+
==========
51+
52+
- ``CLI::setInputOutput()`` can set the ``MockInputOutput`` instance to the ``CLI`` class.
53+
- ``CLI::resetInputOutput()`` resets the ``InputOutput`` instance in the ``CLI`` class.
54+
- ``MockInputOutput::setInputs()`` sets the user input array.
55+
- ``MockInputOutput::getOutput()`` gets the command output.
56+
57+
The following test code is to test the command ``spark db:table``:
58+
59+
.. literalinclude:: overview/021.php
60+
61+
***********************
62+
Without MockInputOutput
63+
***********************
64+
565
.. _testing-cli-output:
666

767
Testing CLI Output
868
==================
969

70+
.. _stream-filter-trait:
71+
1072
StreamFilterTrait
1173
-----------------
1274

@@ -17,10 +79,11 @@ StreamFilterTrait
1779
You may need to test things that are difficult to test. Sometimes, capturing a stream, like PHP's own STDOUT, or STDERR,
1880
might be helpful. The ``StreamFilterTrait`` helps you capture the output from the stream of your choice.
1981

20-
**Overview of methods**
82+
How to Use
83+
^^^^^^^^^^
2184

22-
- ``StreamFilterTrait::getStreamFilterBuffer()`` Get the captured data from the buffer.
23-
- ``StreamFilterTrait::resetStreamFilterBuffer()`` Reset captured data.
85+
- ``StreamFilterTrait::getStreamFilterBuffer()`` gets the captured data from the buffer.
86+
- ``StreamFilterTrait::resetStreamFilterBuffer()`` resets captured data.
2487

2588
An example demonstrating this inside one of your test cases:
2689

@@ -32,6 +95,8 @@ See :ref:`Testing Traits <testing-overview-traits>`.
3295
If you override the ``setUp()`` or ``tearDown()`` methods in your test, then you must call the ``parent::setUp()`` and
3396
``parent::tearDown()`` methods respectively to configure the ``StreamFilterTrait``.
3497

98+
.. _ci-test-stream-filter:
99+
35100
CITestStreamFilter
36101
------------------
37102

@@ -40,7 +105,8 @@ CITestStreamFilter
40105
If you need to capture streams in only one test, then instead of using the StreamFilterTrait trait, you can manually
41106
add a filter to streams.
42107

43-
**Overview of methods**
108+
How to Use
109+
^^^^^^^^^^
44110

45111
- ``CITestStreamFilter::registration()`` Filter registration.
46112
- ``CITestStreamFilter::addOutputFilter()`` Adding a filter to the output stream.
@@ -55,6 +121,8 @@ add a filter to streams.
55121
Testing CLI Input
56122
=================
57123

124+
.. _php-stream-wrapper:
125+
58126
PhpStreamWrapper
59127
----------------
60128

@@ -68,7 +136,8 @@ such as ``CLI::prompt()``, ``CLI::wait()``, and ``CLI::input()``.
68136
see `The streamWrapper class <https://www.php.net/manual/en/class.streamwrapper.php>`_
69137
in the PHP maual.
70138

71-
**Overview of methods**
139+
How to Use
140+
^^^^^^^^^^
72141

73142
- ``PhpStreamWrapper::register()`` Register the ``PhpStreamWrapper`` to the ``php`` protocol.
74143
- ``PhpStreamWrapper::restore()`` Restore the php protocol wrapper back to the PHP built-in wrapper.
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
3+
use CodeIgniter\CLI\CLI;
4+
use CodeIgniter\Test\CIUnitTestCase;
5+
use CodeIgniter\Test\DatabaseTestTrait;
6+
use CodeIgniter\Test\Mock\MockInputOutput;
7+
8+
final class DbTableTest extends CIUnitTestCase
9+
{
10+
use DatabaseTestTrait;
11+
12+
protected $migrateOnce = true;
13+
14+
public function testDbTable(): void
15+
{
16+
// Set MockInputOutput to CLI.
17+
$io = new MockInputOutput();
18+
CLI::setInputOutput($io);
19+
20+
// User will input "a" (invalid value) and "0".
21+
$io->setInputs(['a', '0']);
22+
23+
command('db:table');
24+
25+
// Get the whole output string.
26+
$output = $io->getOutput();
27+
28+
$expected = 'Which table do you want to see? [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]: a';
29+
$this->assertStringContainsString($expected, $output);
30+
31+
$expected = 'Data of Table "db_migrations":';
32+
$this->assertStringContainsString($expected, $output);
33+
34+
// Remove MockInputOutput.
35+
CLI::resetInputOutput();
36+
}
37+
}

0 commit comments

Comments
 (0)