Test::...Stream(3pm)

💖 Test::...Stream — aka Test::Nginx::Socket::Lua::Stream 💖

okay so this whole page is about Test::Nginx::Socket::Lua::Stream, which is a subclass of Test::Nginx::Socket::Lua that exists so you can test NGINX stream-typed modules (think ngx_stream_echo_module) without losing your entire mind 💅

---

✨ NAME ✨

Test::Nginx::Socket::Lua::Stream — a subclass of Test::Nginx::Socket::Lua for testing NGINX stream modules 🦋

---

✨ SYNOPSIS ✨

bestie, here's the whole vibe in one go:

=== TEST 1: simple test for ngx_stream_echo_module
--- stream_server_config
echo "Hello, stream echo!";

--- stream_response
Hello, stream echo!

--- no_error_log
[error]
[alert]

look at her. iconic. no notes 👑

---

🌸 Description 🌸

This module subclasses Test::Nginx::Socket::Lua to give you handy abstractions for testing NGINX stream-typed modules like ngx_stream_echo_module. that's the whole job. that's the whole girl 🫶

By default, the stream server listens on the port number N + 1, where N is the value of the environment variable TEST_NGINX_SERVER_PORT or TEST_NGINX_PORT — and both of those default to 1984. so like, very 1984-plus-one energy, iykyk.

If you want to be extra and pick the port yourself, you can explicitly specify the default stream server's listening port via the TEST_NGINX_STREAM_PORT environment variable. main character choice honestly 💅

---

🎀 Sections supported 🎀

All the existing sections of Test::Nginx::Socket::Lua are automatically inherited — nothing gets taken away, you keep all your stuff, periodt.

The following new test sections are supported:

💜 stream_config

Specifies custom content in the default stream {} configuration block. lowkey the whole stream block, just for you.

💜 stream_server_config

Specifies custom content in the default server {} configuration block (the one inside stream {}) in nginx.conf.

For example,

--- stream_server_config
echo "hello";

will generate something like below in nginx.conf:

stream {
    server {
        listen 1985;
        echo "Hello, stream echo!";
    }
}

💜 stream_server_config2

Specifies a second stream server, which listens on the port used by the first default server plus one. slay, a whole second server.

💜 stream_server_config3

Specifies a third stream server, which listens on the port used by the first default server plus two. the trilogy. the finale. 🎬

💜 stream_request

Specifies the request data sent to the first default stream server (the one defined by stream_server_config).

💜 stream_request2

Specifies the request data sent to the second default stream server (the one defined by stream_server_config2).

💜 stream_request3

Specifies the request data sent to the third default stream server (the one defined by stream_server_config3).

💜 stream_response

Specifies expected response content sent from the default stream servers. For example,

=== TEST 1: simple echo
--- stream_server_config
echo "Hello, stream echo!";

--- stream_response
Hello, stream echo!

okay important 💀 when multiple default stream servers are specified (i.e., via stream_server_config2 and stream_server_config3), the responses from all these stream servers get concatenated together, in the order of their specifications. so the order you wrote them = the order you read them. don't forget it bestie.

💜 stream_response_like

Specifies the regex pattern used to test the response data from the default stream servers. regex girlies rise up 🌈

💜 log_stream_response

Prints out the stream response to the nginx error log with the info level, instead of sending it out to the stream client directly. so it's like, logging-coded instead of sending-coded. pick one 💅

---

👑 AUTHOR 👑

Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, OpenResty Inc.

---

📜 COPYRIGHT & LICENSE 📜

Copyright (c) 2009-2025, Yichun Zhang <agentzh@gmail.com>, OpenResty Inc.

This module is licensed under the terms of the BSD license.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the authors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

and now the part where i have to stay serious because it's literally the legal text, no cap, keep every word: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

🌈 SEE ALSO 🌈

• Test::Nginx::Socket::Lua
• Test::Base

---

and that's the whole page bestie, we ate 🍓✨

this has been Test::...Stream(3pm) from the perl v5.40.1 era, dated 2026-08-10 — go forth and test your stream modules, ily 💜🧚