since: 2.80


g_test_trap_subprocess_with_envp (
  const char* test_path,
  const char* const* envp,
  guint64 usec_timeout,
  GTestSubprocessFlags test_flags


Respawns the test program to run only test_path in a subprocess with the given envp environment.

This can be used for a test case that might not return, or that might abort.

If test_path is NULL then the same test is re-run in a subprocess. You can use g_test_subprocess() to determine whether the test is in a subprocess or not.

test_path can also be the name of the parent test, followed by “/subprocess/” and then a name for the specific subtest (or just ending with “/subprocess” if the test only has one child test); tests with names of this form will automatically be skipped in the parent process.

If envp is NULL, the parent process’ environment will be inherited.

If usec_timeout is non-0, the test subprocess is aborted and considered failing if its run time exceeds it.

The subprocess behavior can be configured with the GTestSubprocessFlags flags.

You can use methods such as g_test_trap_assert_passed(), g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to check the results of the subprocess. (But note that g_test_trap_assert_stdout() and g_test_trap_assert_stderr() cannot be used if test_flags specifies that the child should inherit the parent stdout/stderr.)

If your main () needs to behave differently in the subprocess, you can call g_test_subprocess() (after calling g_test_init()) to see whether you are in a subprocess.

Internally, this function tracks the child process using g_child_watch_source_new(), so your process must not ignore SIGCHLD, and must not attempt to watch or wait for the child process via another mechanism.

The following example tests that calling my_object_new(1000000) will abort with an error message.

  static void
  test_create_large_object (void)
    if (g_test_subprocess ())
        my_object_new (1000000);

    // Reruns this same test in a subprocess
    g_test_trap_subprocess (NULL, 0, G_TEST_SUBPROCESS_DEFAULT);
    g_test_trap_assert_failed ();
    g_test_trap_assert_stderr ("*ERROR*too large*");

  static void
  test_different_username (void)
    if (g_test_subprocess ())
        // Code under test goes here
        g_message ("Username is now simulated as %s", g_getenv ("USER"));

    // Reruns this same test in a subprocess
    g_autoptr(GStrv) envp = g_get_environ ();
    envp = g_environ_setenv (g_steal_pointer (&envp), "USER", "charlie", TRUE);
    g_test_trap_subprocess_with_envp (NULL, envp, 0, G_TEST_SUBPROCESS_DEFAULT);
    g_test_trap_assert_passed ();
    g_test_trap_assert_stdout ("Username is now simulated as charlie");

  main (int argc, char **argv)
    g_test_init (&argc, &argv, NULL);

    g_test_add_func ("/myobject/create-large-object",
    g_test_add_func ("/myobject/different-username",
    return g_test_run ();

Available since: 2.80



Type: const char*

Test to run in a subprocess.

The argument can be NULL.
The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.

Type: An array of filename

Environment to run the test in, or NULL to inherit the parent’s environment. This must be in the GLib filename encoding.

The argument can be NULL.
The array must be NULL-terminated.
The data is owned by the caller of the function.
Each element is a file system path, using the OS encoding.

Type: guint64

Timeout for the subprocess test in micro seconds.


Type: GTestSubprocessFlags

Flags to modify subprocess behaviour.