view release on metacpan or  search on metacpan

lib/PAGI/Test/Client.pm  view on Meta::CPAN

    # Simple hash
    headers => { Authorization => 'Bearer xyz' }

    # Multiple values (arrayref in hash)
    headers => { Accept => ['application/json', 'text/html'] }

    # Arrayref of pairs (preserves order)
    headers => [['X-Custom', 'first'], ['X-Custom', 'second']]

Request headers with the same name as client default headers will B<replace>
the defaults (not append).

=item query => { ... } or [ [...], [...] ]

Query string parameters. Supports multiple formats:

    # Simple hash
    query => { q => 'perl' }

    # Multiple values
    query => { tag => ['perl', 'async'] }  # ?tag=perl&tag=async

    # Arrayref of pairs
    query => [['tag', 'perl'], ['tag', 'async']]

B<Note:> Query params are B<appended> to any existing query string in the path.
To avoid duplicates, put all params either in the path or in the query option,
not both with the same key.

=item json => { ... }

JSON request body. Automatically sets Content-Type to application/json.

=item form => { ... } or [ [...], [...] ]

Form-encoded request body. Sets Content-Type to application/x-www-form-urlencoded.
Supports multiple formats:

    # Simple hash
    form => { user => 'admin', pass => 'secret' }

    # Multiple values (checkboxes, multi-select)
    form => { colors => ['red', 'blue', 'green'] }

    # Arrayref of pairs
    form => [['color', 'red'], ['color', 'blue']]

=item body => $bytes

Raw request body bytes.

=back

=head1 LIMITATIONS

=over 4

=item *

HTTP request bodies are delivered as a single C<http.request> event. This
client does B<not> currently simulate multi-event request body streaming or
disconnects mid-request-body.

=item *

HTTP response trailers (C<http.response.trailers>) are not exposed through
L<PAGI::Test::Response>. If your application depends on trailer semantics,
test it against L<PAGI::Server>.

=item *

This client invokes the app directly and does not simulate transport-level
behavior such as chunked transfer framing, socket backpressure, kernel write
ordering, TLS, or HTTP/2.

=item *

Lifespan support is intended for basic shared-state tests. It is lighter-weight
than the real server lifecycle and should not be treated as a full compliance
test for startup/shutdown behavior.

=item *

WebSocket and SSE testing is delegated to L<PAGI::Test::WebSocket> and
L<PAGI::Test::SSE>, which intentionally provide simplified in-process models
of those protocols.

=back

=head1 SESSION METHODS

=head2 cookies

    my $hashref = $client->cookies;

Returns all current session cookies.

=head2 cookie

    my $value = $client->cookie('session_id');

Returns a specific cookie value.

=head2 set_cookie

    $client->set_cookie('theme', 'dark');

Manually sets a cookie.

=head2 clear_cookies

    $client->clear_cookies;

Clears all session cookies.

=head1 WEBSOCKET

=head2 websocket

    # Callback style (auto-close)
    $client->websocket('/ws', sub {