Skip to content

Commit f70b77a

Browse files
committed
docs: move Testing CLI to a new page
1 parent 19e1395 commit f70b77a

File tree

3 files changed

+87
-83
lines changed

3 files changed

+87
-83
lines changed

user_guide_src/source/testing/cli.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
####################
2+
Testing CLI Commands
3+
####################
4+
5+
.. _testing-cli-output:
6+
7+
Testing CLI Output
8+
==================
9+
10+
StreamFilterTrait
11+
-----------------
12+
13+
.. versionadded:: 4.3.0
14+
15+
**StreamFilterTrait** provides an alternate to these helper methods.
16+
17+
You may need to test things that are difficult to test. Sometimes, capturing a stream, like PHP's own STDOUT, or STDERR,
18+
might be helpful. The ``StreamFilterTrait`` helps you capture the output from the stream of your choice.
19+
20+
**Overview of methods**
21+
22+
- ``StreamFilterTrait::getStreamFilterBuffer()`` Get the captured data from the buffer.
23+
- ``StreamFilterTrait::resetStreamFilterBuffer()`` Reset captured data.
24+
25+
An example demonstrating this inside one of your test cases:
26+
27+
.. literalinclude:: overview/018.php
28+
29+
The ``StreamFilterTrait`` has a configurator that is called automatically.
30+
See :ref:`Testing Traits <testing-overview-traits>`.
31+
32+
If you override the ``setUp()`` or ``tearDown()`` methods in your test, then you must call the ``parent::setUp()`` and
33+
``parent::tearDown()`` methods respectively to configure the ``StreamFilterTrait``.
34+
35+
CITestStreamFilter
36+
------------------
37+
38+
**CITestStreamFilter** for manual/single use.
39+
40+
If you need to capture streams in only one test, then instead of using the StreamFilterTrait trait, you can manually
41+
add a filter to streams.
42+
43+
**Overview of methods**
44+
45+
- ``CITestStreamFilter::registration()`` Filter registration.
46+
- ``CITestStreamFilter::addOutputFilter()`` Adding a filter to the output stream.
47+
- ``CITestStreamFilter::addErrorFilter()`` Adding a filter to the error stream.
48+
- ``CITestStreamFilter::removeOutputFilter()`` Removing a filter from the output stream.
49+
- ``CITestStreamFilter::removeErrorFilter()`` Removing a filter from the error stream.
50+
51+
.. literalinclude:: overview/020.php
52+
53+
.. _testing-cli-input:
54+
55+
Testing CLI Input
56+
=================
57+
58+
PhpStreamWrapper
59+
----------------
60+
61+
.. versionadded:: 4.3.0
62+
63+
**PhpStreamWrapper** provides a way to write tests for methods that require user input,
64+
such as ``CLI::prompt()``, ``CLI::wait()``, and ``CLI::input()``.
65+
66+
.. note:: The PhpStreamWrapper is a stream wrapper class.
67+
If you don't know PHP's stream wrapper,
68+
see `The streamWrapper class <https://www.php.net/manual/en/class.streamwrapper.php>`_
69+
in the PHP maual.
70+
71+
**Overview of methods**
72+
73+
- ``PhpStreamWrapper::register()`` Register the ``PhpStreamWrapper`` to the ``php`` protocol.
74+
- ``PhpStreamWrapper::restore()`` Restore the php protocol wrapper back to the PHP built-in wrapper.
75+
- ``PhpStreamWrapper::setContent()`` Set the input data.
76+
77+
.. important:: The PhpStreamWrapper is intended for only testing ``php://stdin``.
78+
But when you register it, it handles all the `php protocol <https://www.php.net/manual/en/wrappers.php.php>`_ streams,
79+
such as ``php://stdout``, ``php://stderr``, ``php://memory``.
80+
So it is strongly recommended that ``PhpStreamWrapper`` be registered/unregistered
81+
only when needed. Otherwise, it will interfere with other built-in php streams
82+
while registered.
83+
84+
An example demonstrating this inside one of your test cases:
85+
86+
.. literalinclude:: overview/019.php

user_guide_src/source/testing/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ The following sections should get you quickly testing your applications.
1414
Controller Testing <controllers>
1515
HTTP Testing <feature>
1616
response
17+
cli
1718
benchmark
1819
debugging
1920
Mocking <mocking>

user_guide_src/source/testing/overview.rst

Lines changed: 0 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -262,86 +262,3 @@ component name:
262262
.. literalinclude:: overview/017.php
263263

264264
.. note:: All component Factories are reset by default between each test. Modify your test case's ``$setUpMethods`` if you need instances to persist.
265-
266-
.. _testing-cli-output:
267-
268-
Testing CLI Output
269-
==================
270-
271-
StreamFilterTrait
272-
-----------------
273-
274-
.. versionadded:: 4.3.0
275-
276-
**StreamFilterTrait** provides an alternate to these helper methods.
277-
278-
You may need to test things that are difficult to test. Sometimes, capturing a stream, like PHP's own STDOUT, or STDERR,
279-
might be helpful. The ``StreamFilterTrait`` helps you capture the output from the stream of your choice.
280-
281-
**Overview of methods**
282-
283-
- ``StreamFilterTrait::getStreamFilterBuffer()`` Get the captured data from the buffer.
284-
- ``StreamFilterTrait::resetStreamFilterBuffer()`` Reset captured data.
285-
286-
An example demonstrating this inside one of your test cases:
287-
288-
.. literalinclude:: overview/018.php
289-
290-
The ``StreamFilterTrait`` has a configurator that is called automatically.
291-
See :ref:`Testing Traits <testing-overview-traits>`.
292-
293-
If you override the ``setUp()`` or ``tearDown()`` methods in your test, then you must call the ``parent::setUp()`` and
294-
``parent::tearDown()`` methods respectively to configure the ``StreamFilterTrait``.
295-
296-
CITestStreamFilter
297-
------------------
298-
299-
**CITestStreamFilter** for manual/single use.
300-
301-
If you need to capture streams in only one test, then instead of using the StreamFilterTrait trait, you can manually
302-
add a filter to streams.
303-
304-
**Overview of methods**
305-
306-
- ``CITestStreamFilter::registration()`` Filter registration.
307-
- ``CITestStreamFilter::addOutputFilter()`` Adding a filter to the output stream.
308-
- ``CITestStreamFilter::addErrorFilter()`` Adding a filter to the error stream.
309-
- ``CITestStreamFilter::removeOutputFilter()`` Removing a filter from the output stream.
310-
- ``CITestStreamFilter::removeErrorFilter()`` Removing a filter from the error stream.
311-
312-
.. literalinclude:: overview/020.php
313-
314-
.. _testing-cli-input:
315-
316-
Testing CLI Input
317-
=================
318-
319-
PhpStreamWrapper
320-
----------------
321-
322-
.. versionadded:: 4.3.0
323-
324-
**PhpStreamWrapper** provides a way to write tests for methods that require user input,
325-
such as ``CLI::prompt()``, ``CLI::wait()``, and ``CLI::input()``.
326-
327-
.. note:: The PhpStreamWrapper is a stream wrapper class.
328-
If you don't know PHP's stream wrapper,
329-
see `The streamWrapper class <https://www.php.net/manual/en/class.streamwrapper.php>`_
330-
in the PHP maual.
331-
332-
**Overview of methods**
333-
334-
- ``PhpStreamWrapper::register()`` Register the ``PhpStreamWrapper`` to the ``php`` protocol.
335-
- ``PhpStreamWrapper::restore()`` Restore the php protocol wrapper back to the PHP built-in wrapper.
336-
- ``PhpStreamWrapper::setContent()`` Set the input data.
337-
338-
.. important:: The PhpStreamWrapper is intended for only testing ``php://stdin``.
339-
But when you register it, it handles all the `php protocol <https://www.php.net/manual/en/wrappers.php.php>`_ streams,
340-
such as ``php://stdout``, ``php://stderr``, ``php://memory``.
341-
So it is strongly recommended that ``PhpStreamWrapper`` be registered/unregistered
342-
only when needed. Otherwise, it will interfere with other built-in php streams
343-
while registered.
344-
345-
An example demonstrating this inside one of your test cases:
346-
347-
.. literalinclude:: overview/019.php

0 commit comments

Comments
 (0)