tezt 4.1.0 · OCaml Package

Managing external processes.

This module is only available in tezt, not in tezt.core and tezt.js.

type t

A process which was spawned.

type hooks = Tezt_core.Process_hooks.t = {

on_log : string -> unit;
(*
A hook that is called with every line that is being logged.
*)
on_spawn : string -> string list -> unit;
(*
A hook that is called whenever a process is being spawned. The first parameter is the command and the second are its arguments.
*)

}

Process can have some hooks attached when spawned.

val spawn : 
  ?runner:Runner.t ->
  ?log_command:bool ->
  ?log_status_on_exit:bool ->
  ?log_output:bool ->
  ?name:string ->
  ?color:Tezt_core.Log.Color.t ->
  ?env:string Tezt_core.Base.String_map.t ->
  ?hooks:hooks ->
  string ->
  string list ->
  t

Create a process which starts running in the background.

Usage: spawn command arguments

If log_command is true (which is the default), log the command being executed.

If log_status_on_exit is true (which is the default), log the exit code when the process terminates.

If log_output is true (which is the default), log the stdout and stderr output.

Parameter name specifies the prefix (in brackets) that is added to each logged output line. Parameter color specifies the color of those output lines.

Parameter hooks allows to attach some hooks to the process. Warning: if you use hooks, all the process output is stored in memory until it finishes. So this can use a lot of memory. Also, note that stdout is sent to the hook first, then stderr. The two outputs are not interleaved. This is to make it more predictable for regression tests.

Note that this function can only be called if Background.register is allowed (which is the case inside functions given to Test.register).

Parameter runner specifies the runner on which to run the process. If unspecified, the process runs locally. Otherwise, it runs on the given runner using SSH.

Example: spawn "git" [ "log"; "-p" ]

val spawn_with_stdin : 
  ?runner:Runner.t ->
  ?log_command:bool ->
  ?log_status_on_exit:bool ->
  ?log_output:bool ->
  ?name:string ->
  ?color:Tezt_core.Log.Color.t ->
  ?env:string Tezt_core.Base.String_map.t ->
  ?hooks:hooks ->
  string ->
  string list ->
  t * Lwt_io.output_channel

Same as spawn, but with a channel to send data to the process stdin.

val terminate : ?timeout:float -> t -> unit

Send SIGTERM to a process.

If timeout is specified, this registers a background promise that causes SIGKILL to be sent if the process does not terminate after timeout seconds.

val kill : t -> unit

Send SIGKILL to a process.

val wait : t -> Unix.process_status Lwt.t

Wait until a process terminates and return its status.

val validate_status : 
  ?expect_failure:bool ->
  Unix.process_status ->
  (unit, [ `Invalid_status of string ]) result

Check the exit status of a process.

If not expect_failure and exit code is not 0, or if expect_failure and exit code is 0, or if the process was killed, return Error (`Invalid_status reason). Else, return Ok ().

val check : ?expect_failure:bool -> t -> unit Lwt.t

Wait until a process terminates and check its status.

See validate_status to see status validation rules.

val check_error : ?exit_code:int -> ?msg:Tezt_core.Base.rex -> t -> unit Lwt.t

Wait until a process terminates and check its status.

If exit_code is different than t exit code, or if msg does not match the stderr output, fail the test.

If exit_code is not specified, any non-zero code is accepted. If no msg is given, the stderr is ignored.

val check_and_read_stdout : ?expect_failure:bool -> t -> string Lwt.t

Wait until a process terminates and read its standard output.

Fail the test if the process failed, unless expect_failure, in which case fail if the process succeeds.

val check_and_read_stderr : ?expect_failure:bool -> t -> string Lwt.t

Wait until a process terminates and read its standard error.

Fail the test if the process failed, unless expect_failure, in which case fail if the process succeeds.

val check_and_read_both : ?expect_failure:bool -> t -> (string * string) Lwt.t

Wait until a process terminates and read both its standard output and its standard error.

Fail the test if the process failed, unless expect_failure, in which case fail if the process succeeds.

val run : 
  ?log_status_on_exit:bool ->
  ?name:string ->
  ?color:Tezt_core.Log.Color.t ->
  ?env:string Tezt_core.Base.String_map.t ->
  ?hooks:hooks ->
  ?expect_failure:bool ->
  string ->
  string list ->
  unit Lwt.t

Spawn a process, wait for it to terminate, and check its status.

val clean_up : ?timeout:float -> unit -> unit Lwt.t

Terminate all live processes created using spawn and wait for them to terminate.

timeout is passed to terminate, with a default value of 60. (one minute).

val stdout : t -> Lwt_io.input_channel

Channel from which you can read the standard output of a process.

val stderr : t -> Lwt_io.input_channel

Channel from which you can read the standard error output of a process.

val name : t -> string

Get the name which was given to spawn.

val pid : t -> int

Get the PID of the given process.

val run_and_read_stdout : 
  ?log_status_on_exit:bool ->
  ?name:string ->
  ?color:Tezt_core.Log.Color.t ->
  ?env:string Tezt_core.Base.String_map.t ->
  ?hooks:hooks ->
  ?expect_failure:bool ->
  string ->
  string list ->
  string Lwt.t

Spawn a process such as run and return its standard output.

Fail the test if the process failed, unless expect_failure, in which case fail if the process succeeds.

val run_and_read_stderr : 
  ?log_status_on_exit:bool ->
  ?name:string ->
  ?color:Tezt_core.Log.Color.t ->
  ?env:string Tezt_core.Base.String_map.t ->
  ?hooks:hooks ->
  ?expect_failure:bool ->
  string ->
  string list ->
  string Lwt.t

Spawn a process such as run and return its standard error.

Fail the test if the process failed, unless expect_failure, in which case fail if the process succeeds.

val program_path : string -> string option Lwt.t

program_path p returns Some path if the shell command command -v p succeeds and prints path. Returns None otherwise.

package tezt