---
name: "Perlbal::Test"
section: "3pm"
platform: "linux"
package: "libperlbal-perl"
version: "1.80-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Perlbal::Test"
---

# Perlbal::Test(3pm)

Test harness for perlbal server

## NAME

Perlbal::Test - Test harness for perlbal server

## SYNOPSIS

\#  my `$msock` = **Perlbal::Test::start\_server()**;

## DESCRIPTION

Perlbal::Test provides access to a perlbal server running on the local host, for testing purposes.

The server can be an already-existing server, a child process, or the current process.

Various functions are provided to interact with the server.

## FUNCTIONS

## ***mgmt\_port()***

Return the current management port number.

## *dump\_res($http\_response)*

Return a readable string formatted from an HTTP::Response object. Only the first 80 characters of returned content are returned.

## ***tempdir()***

Return a newly created temporary directory. The directory will be removed automatically upon program exit.

## ***new\_port()***

Return the next free port number in the series. Port numbers are assigned starting at 60000.

## ***test\_port()***

Return 1 if the port is free to use for listening on `$free_port` else return 0.

## *filecontent($file*\>

Return a string containing the contents of the file `$file`. If `$file` cannot be opened, then return undef.

## *foreach\_aio($callback)*

Set the server into each AIO mode (none, ioaio) and call the specified callback function with the mode name as argument.

## *manage($cmd, %opts)*

Send a command `$cmd` to the server, and return the response line from the server.

Optional arguments are:

```
  quiet_failure => 1
```

Output a warning if the response indicated an error, unless `$opts`{quiet\_failure} is true, or the command was 'shutdown' (which doesn't return a response).

## *manage\_multi($cmd)*

Send a command `$cmd` to the server, and return a multi-line response. Return the number zero if there was an error or no response.

## *start\_server($conf)*

Optionally start a perlbal server and return a socket connected to its management port.

The argument `$conf` is a string specifying initial configuration commands.

If the environment variable TEST\_PERLBAL\_FOREGROUND is set to a true value then a server will be started in the foreground, in which case this function does not return. When the server function finishes, **exit()** will be called to terminate the process.

If the environment variable TEST\_PERLBAL\_USE\_EXISTING is set to a true value then a socket will be returned which is connected to an existing server's management port.

Otherwise, a child process is forked and a socket is returned which is connected to the child's management port.

The management port is assigned automatically, a new port number each time this function is called. The starting port number is 60000.

## ***msock()***

Return a reference to the socket connected to the server's management port.

## ***ua()***

Return a new instance of LWP::UserAgent.

## *wait\_on\_child($pid, $port)*

Return a socket which is connected to a child process.

`$pid` specifies the child process id, and `$port` is the port number on which the child is listening.

Several attempts are made; if the child dies or a connection cannot be made within 5 seconds then this function dies with an error message.

## *resp\_from\_sock($sock)*

Read an HTTP response from a socket and return it as an HTTP::Response object

In scalar mode, return only the `$http_response` object.

In array mode, return an array of ($http\_response, `$firstline`) where `$firstline` is the first line read from the socket, for example:

"HTTP/1.1 200 OK"