More test suites refactoring

They are now properly documented and the listener name is
automatically specified thanks to a new ct_helper function.

3 files changed, 91 insertions, 104 deletions

diff --git a/test/acceptor_SUITE.erl b/test/acceptor_SUITE.erl
index 7c3b831..93952ca 100644
--- a/test/acceptor_SUITE.erl
+++ b/test/acceptor_SUITE.erl
@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <[email protected]>
+%% Copyright (c) 2011-2015, Loïc Hoguin <[email protected]>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -16,6 +16,7 @@
 -compile(export_all).
 
 -import(ct_helper, [doc/1]).
+-import(ct_helper, [name/0]).
 
 %% ct.
 
@@ -64,7 +65,7 @@ misc_bad_transport(_) ->
 
 ssl_accept_error(_) ->
 	doc("Acceptor must not crash if client disconnects in the middle of SSL handshake."),
-	Name = ssl_accept_error,
+	Name = name(),
 	Opts = ct_helper:get_certs_from_ets(),
 	{ok, ListenerSup} = ranch:start_listener(Name, 1, ranch_ssl, Opts, echo_protocol, []),
 	Port = ranch:get_port(Name),
@@ -80,7 +81,7 @@ ssl_accept_error(_) ->
 
 ssl_accept_socket(_) ->
 	doc("Ensure that listener can use an externally opened SSL listen socket."),
-	Name = ssl_accept_socket,
+	Name = name(),
 	Opts = ct_helper:get_certs_from_ets(),
 	{ok, S} = ssl:listen(0, [binary, {active, false}, {packet, raw}, {reuseaddr, true}|Opts]),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_ssl, [{socket, S}], echo_protocol, []),
@@ -96,7 +97,7 @@ ssl_accept_socket(_) ->
 
 ssl_active_echo(_) ->
 	doc("Ensure that active mode works with SSL transport."),
-	Name = ssl_active_echo,
+	Name = name(),
 	Opts = ct_helper:get_certs_from_ets(),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_ssl, Opts, active_echo_protocol, []),
 	Port = ranch:get_port(Name),
@@ -111,7 +112,7 @@ ssl_active_echo(_) ->
 
 ssl_echo(_) ->
 	doc("Ensure that passive mode works with SSL transport."),
-	Name = ssl_echo,
+	Name = name(),
 	Opts = ct_helper:get_certs_from_ets(),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_ssl, Opts, echo_protocol, []),
 	Port = ranch:get_port(Name),
@@ -128,7 +129,7 @@ ssl_echo(_) ->
 
 tcp_accept_socket(_) ->
 	doc("Ensure that listener can use an externally opened TCP listen socket."),
-	Name = tcp_accept_socket,
+	Name = name(),
 	{ok, S} = gen_tcp:listen(0, [binary, {active, false}, {packet, raw}, {reuseaddr, true}]),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_tcp, [{socket, S}], echo_protocol, []),
 	Port = ranch:get_port(Name),
@@ -143,7 +144,7 @@ tcp_accept_socket(_) ->
 
 tcp_active_echo(_) ->
 	doc("Ensure that active mode works with TCP transport."),
-	Name = tcp_active_echo,
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_tcp, [], active_echo_protocol, []),
 	Port = ranch:get_port(Name),
 	{ok, Socket} = gen_tcp:connect("localhost", Port, [binary, {active, false}, {packet, raw}]),
@@ -157,7 +158,7 @@ tcp_active_echo(_) ->
 
 tcp_echo(_) ->
 	doc("Ensure that passive mode works with TCP transport."),
-	Name = tcp_echo,
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_tcp, [], echo_protocol, []),
 	Port = ranch:get_port(Name),
 	{ok, Socket} = gen_tcp:connect("localhost", Port, [binary, {active, false}, {packet, raw}]),
@@ -170,20 +171,19 @@ tcp_echo(_) ->
 	ok.
 
 tcp_inherit_options(_) ->
-	Name = tcp_inherit_options,
-	TcpOptions = [{nodelay, false}, {send_timeout_close, false}],
-	{ok, _} = ranch:start_listener(Name, 4, ranch_tcp,
-			TcpOptions,
-			check_tcp_options, [{pid, self()} | TcpOptions]),
+	doc("Ensure TCP options are inherited in the protocol."),
+	Name = name(),
+	Opts = [{nodelay, false}, {send_timeout_close, false}],
+	{ok, _} = ranch:start_listener(Name, 4, ranch_tcp, Opts, check_tcp_options, [{pid, self()} | Opts]),
 	Port = ranch:get_port(Name),
-	{ok, Socket} = gen_tcp:connect("localhost", Port,
-			[binary, {active, true}, {packet, raw}]),
+	{ok, Socket} = gen_tcp:connect("localhost", Port, [binary, {active, true}, {packet, raw}]),
 	receive checked -> ok after 1000 -> error(timeout) end,
 	ok = gen_tcp:close(Socket),
 	ok = ranch:stop_listener(Name).
 
 tcp_max_connections(_) ->
-	Name = tcp_max_connections,
+	doc("Ensure the max_connections option actually limits connections."),
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{max_connections, 10}],
 		notify_and_wait_protocol, [{msg, connected}, {pid, self()}]),
@@ -195,7 +195,8 @@ tcp_max_connections(_) ->
 	ok = ranch:stop_listener(Name).
 
 tcp_max_connections_and_beyond(_) ->
-	Name = tcp_max_connections_and_beyond,
+	doc("Ensure the max_connections option works when connections are removed from the count."),
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{max_connections, 10}],
 		remove_conn_and_wait_protocol, [{remove, true}]),
@@ -203,10 +204,8 @@ tcp_max_connections_and_beyond(_) ->
 	ok = connect_loop(Port, 10, 0),
 	receive after 250 -> ok end,
 	0 = ranch_server:count_connections(Name),
-	10 = length(supervisor:which_children(
-		ranch_server:get_connections_sup(Name))),
-	Counts = supervisor:count_children(
-		ranch_server:get_connections_sup(Name)),
+	10 = length(supervisor:which_children(ranch_server:get_connections_sup(Name))),
+	Counts = supervisor:count_children(ranch_server:get_connections_sup(Name)),
 	{_, 1} = lists:keyfind(specs, 1, Counts),
 	{_, 0} = lists:keyfind(supervisors, 1, Counts),
 	{_, 10} = lists:keyfind(active, 1, Counts),
@@ -216,16 +215,15 @@ tcp_max_connections_and_beyond(_) ->
 	ok = connect_loop(Port, 10, 0),
 	receive after 250 -> ok end,
 	10 = ranch_server:count_connections(Name),
-	20 = length(supervisor:which_children(
-		ranch_server:get_connections_sup(Name))),
-	Counts2 = supervisor:count_children(
-		ranch_server:get_connections_sup(Name)),
+	20 = length(supervisor:which_children(ranch_server:get_connections_sup(Name))),
+	Counts2 = supervisor:count_children(ranch_server:get_connections_sup(Name)),
 	{_, 20} = lists:keyfind(active, 1, Counts2),
 	{_, 20} = lists:keyfind(workers, 1, Counts2),
 	ok = ranch:stop_listener(Name).
 
 tcp_max_connections_infinity(_) ->
-	Name = tcp_max_connections_infinity,
+	doc("Set the max_connections option from 10 to infinity and back to 10."),
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{max_connections, 10}],
 		notify_and_wait_protocol, [{msg, connected}, {pid, self()}]),
@@ -245,7 +243,8 @@ tcp_max_connections_infinity(_) ->
 	ok = ranch:stop_listener(Name).
 
 tcp_set_max_connections(_) ->
-	Name = tcp_set_max_connections,
+	doc("Ensure that changing the max_connections option to a larger value allows for more connections."),
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{max_connections, 10}],
 		notify_and_wait_protocol, [{msg, connected}, {pid, self()}]),
@@ -260,9 +259,8 @@ tcp_set_max_connections(_) ->
 	ok = ranch:stop_listener(Name).
 
 tcp_set_max_connections_clean(_) ->
-	%% This is a regression test to check that setting max connections does not
-	%% cause any processes to crash.
-	Name = tcp_set_max_connections_clean,
+	doc("Ensure that setting max_connections does not crash any process."),
+	Name = name(),
 	{ok, ListSupPid} = ranch:start_listener(Name, 4, ranch_tcp,
 			[{max_connections, 4}],
 			notify_and_wait_protocol, [{msg, connected}, {pid, self()}]),
@@ -273,7 +271,7 @@ tcp_set_max_connections_clean(_) ->
 	Port = ranch:get_port(Name),
 	N = 20,
 	ok = connect_loop(Port, N*5, 0),
-	%% Randomly set max connections.
+	%% Randomly set max_connections.
 	[spawn(ranch, set_max_connections, [Name, Max]) ||
 		Max <- lists:flatten(lists:duplicate(N, [6, 4, 8, infinity]))],
 	receive
@@ -287,7 +285,8 @@ tcp_set_max_connections_clean(_) ->
 	ok = ranch:stop_listener(Name).
 
 tcp_upgrade(_) ->
-	Name = tcp_upgrade,
+	doc("Ensure that protocol options can be updated."),
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [],
 		notify_and_wait_protocol, [{msg, connected}, {pid, self()}]),
@@ -303,7 +302,7 @@ tcp_upgrade(_) ->
 
 connection_type_supervisor(_) ->
 	doc("The supervisor connection type must be reflected in the specifications."),
-	Name = connection_type_supervisor,
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{connection_type, supervisor}],
 		echo_protocol, []),
@@ -321,7 +320,7 @@ connection_type_supervisor(_) ->
 
 connection_type_supervisor_separate_from_connection(_) ->
 	doc("The supervisor connection type allows separate supervised and connection processes."),
-	Name = connection_type_supervisor,
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{connection_type, supervisor}],
 		supervisor_separate, []),
@@ -338,9 +337,9 @@ connection_type_supervisor_separate_from_connection(_) ->
 	ok.
 
 supervisor_clean_child_restart(_) ->
-	%% Then we verify that only parts of the supervision tree
-	%% restarted in the case of failure.
-	Name = supervisor_clean_child_restart,
+	doc("Verify that only the relevant parts of the supervision tree restarted "
+		"when the listening socket is closed."),
+	Name = name(),
 	%% Trace socket allocations.
 	_ = erlang:trace(new, true, [call]),
 	1 = erlang:trace_pattern({ranch_tcp, listen, 1},
@@ -377,10 +376,10 @@ supervisor_clean_child_restart(_) ->
 	ok = ranch:stop_listener(Name).
 
 supervisor_clean_conns_sup_restart(_) ->
-	%% Verify that a conns_sup can not register with the same Name as an already
-	%% registered conns_sup that is still alive. Make sure this does not crash
-	%% the ranch_server.
-	Name = supervisor_clean_conns_sup_restart,
+	doc("Verify that a conns_sup can not register with the same name as an already "
+		"registered ranch_conns_sup that is still alive. Make sure this does not crash "
+		"the ranch_server process."),
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name,
 		1, ranch_tcp, [], echo_protocol, []),
 	Server = erlang:whereis(ranch_server),
@@ -397,13 +396,11 @@ supervisor_clean_conns_sup_restart(_) ->
 	ok = ranch:stop_listener(Name).
 
 supervisor_clean_restart(_) ->
-	%% There we verify that mature listener death will not let
-	%% whole supervisor down and also the supervisor itself will
-	%% restart everything properly.
-	Name = supervisor_clean_restart,
+	doc("Verify that killing ranch_conns_sup does not crash everything "
+		"and that it restarts properly."),
+	Name = name(),
 	NbAcc = 4,
-	{ok, Pid} = ranch:start_listener(Name,
-		NbAcc, ranch_tcp, [], echo_protocol, []),
+	{ok, Pid} = ranch:start_listener(Name, NbAcc, ranch_tcp, [], echo_protocol, []),
 	%% Trace supervisor spawns.
 	1 = erlang:trace(Pid, true, [procs, set_on_spawn]),
 	ConnsSup0 = ranch_server:get_connections_sup(Name),
@@ -431,9 +428,8 @@ supervisor_clean_restart(_) ->
 	ok = ranch:stop_listener(Name).
 
 supervisor_conns_alive(_) ->
-	%% And finally we make sure that in the case of partial failure
-	%% live connections are not being killed.
-	Name = supervisor_conns_alive,
+	doc("Ensure that active connections stay open when the listening socket gets closed."),
+	Name = name(),
 	_ = erlang:trace(new, true, [call]),
 	1 = erlang:trace_pattern({ranch_tcp, listen, 1},
 		[{'_', [], [{return_trace}]}], [global]),
@@ -463,7 +459,7 @@ supervisor_conns_alive(_) ->
 
 supervisor_protocol_start_link_crash(_) ->
 	doc("Ensure a protocol start crash does not kill all connections."),
-	Name = supervisor_protocol_start_link_crash,
+	Name = name(),
 	{ok, _} = ranch:start_listener(Name, 1, ranch_tcp, [], crash_protocol, []),
 	ConnsSup = ranch_server:get_connections_sup(Name),
 	Port = ranch:get_port(Name),
@@ -473,14 +469,13 @@ supervisor_protocol_start_link_crash(_) ->
 	ok = ranch:stop_listener(Name).
 
 supervisor_server_recover_state(_) ->
-	%% Verify that if ranch_server crashes it regains its state and monitors
-	%% ranch_conns_sup that were previously registered.
-	Name = supervisor_server_recover_state,
-	{ok, _} = ranch:start_listener(Name, 1,
-			ranch_tcp, [], echo_protocol, []),
+	doc("Ensure that when ranch_server crashes and restarts, it recovers "
+		"its state and continues monitoring the same processes."),
+	Name = name(),
+	{ok, _} = ranch:start_listener(Name, 1, ranch_tcp, [], echo_protocol, []),
 	_ = erlang:trace(new, true, [call]),
 	1 = erlang:trace_pattern({ranch_server, init, 1},
-			[{'_', [], [{return_trace}]}], [global]),
+		[{'_', [], [{return_trace}]}], [global]),
 	ConnsSup = ranch_server:get_connections_sup(Name),
 	ServerPid = erlang:whereis(ranch_server),
 	{monitors, Monitors} = erlang:process_info(ServerPid, monitors),
diff --git a/test/sendfile_SUITE.erl b/test/sendfile_SUITE.erl
index b067ded..c6c9524 100644
--- a/test/sendfile_SUITE.erl
+++ b/test/sendfile_SUITE.erl
@@ -1,4 +1,5 @@
 %% Copyright (c) 2013, James Fish <[email protected]>
+%% Copyright (c) 2015, Loïc Hoguin <[email protected]>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -58,9 +59,8 @@ init_per_group(tcp, Config) ->
 end_per_group(_, _) ->
 	ok.
 
-%% Check can send a whole file given with filename.
-
 filename(Config) ->
+	doc("Use sendfile with a filename."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -73,9 +73,8 @@ filename(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send a whole file with rawfile.
-
 rawfile(Config) ->
+	doc("Use sendfile with a file descriptor (raw file)."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -91,9 +90,8 @@ rawfile(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send a file where Bytes is larger than file size.
-
 rawfile_bytes_large(Config) ->
+	doc("Use sendfile with a file descriptor. Try to send a size larger than file size."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -110,9 +108,8 @@ rawfile_bytes_large(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send whole file when Bytes =:= 0.
-
 rawfile_bytes_zero(Config) ->
+	doc("Use sendfile with a file descriptor. Ensure using a size of 0 sends the whole file."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -128,9 +125,8 @@ rawfile_bytes_zero(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send file where chunk_size is greater than file size.
-
 rawfile_chunk_size_large(Config) ->
+	doc("Use sendfile with a file descriptor. Try to use a chunk size larger than file size."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -138,8 +134,7 @@ rawfile_chunk_size_large(Config) ->
 	{ok, {Server, Client}} = sockets(Config),
 	{ok, RawFile} = file:open(Filename, [read, raw, binary]),
 	Ref = recv(Transport, Server, Size),
-	{ok, Size} = Transport:sendfile(Client, RawFile, 0, Size,
-			[{chunk_size, Size * 2}]),
+	{ok, Size} = Transport:sendfile(Client, RawFile, 0, Size, [{chunk_size, Size * 2}]),
 	{ok, Binary} = result(Ref),
 	{error, timeout} = Transport:recv(Server, 1, 100),
 	{ok, 0} = file:position(RawFile, {cur, 0}),
@@ -147,10 +142,8 @@ rawfile_chunk_size_large(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check send file where offset is larger than file size sends no bytes and
-%% returns {ok, 0}.
-
 rawfile_offset_large(Config) ->
+	doc("Use sendfile with a file descriptor. Ensure using an offset larger than file size sends nothing."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -163,10 +156,9 @@ rawfile_offset_large(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send file with positive Offset and Offset + Bytes larger than file
-%% size.
-
 rawfile_range_large(Config) ->
+	doc("Use sendfile with a file descriptor. "
+		"Set an offset and try to send a size larger than remaining file size."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -188,10 +180,9 @@ rawfile_range_large(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send file with positive Offset and Offset + Bytes less than file
-%% size.
-
 rawfile_range_medium(Config) ->
+	doc("Use sendfile with a file descriptor. "
+		"Set an offset and try to send a size lower than remaining file size."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -212,10 +203,10 @@ rawfile_range_medium(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check can send file with positive Offset, Offset + Bytes less than file
-%% size and Bytes less than chunk_size.
-
 rawfile_range_small(Config) ->
+	doc("Use sendfile with a file descriptor. "
+		"Set an offset and try to send a size lower than remaining file size, "
+		"which is in turn lower than the chunk size."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -226,8 +217,7 @@ rawfile_range_small(Config) ->
 	Offset = 7,
 	Bytes = 19,
 	Ref = recv(Transport, Server, Bytes),
-	{ok, Bytes} = Transport:sendfile(Client, RawFile, Offset, Bytes,
-			[{chunk_size, 16#FFFF}]),
+	{ok, Bytes} = Transport:sendfile(Client, RawFile, Offset, Bytes, [{chunk_size, 16#FFFF}]),
 	Binary2 = binary:part(Binary, Offset, Bytes),
 	{ok, Binary2} = result(Ref),
 	{error, timeout} = Transport:recv(Server, 1, 100),
@@ -236,9 +226,8 @@ rawfile_range_small(Config) ->
 	ok = Transport:close(Client),
 	ok = Transport:close(Server).
 
-%% Check ssl obeys chunk_size.
-
 ssl_chunk_size(Config) ->
+	doc("Use sendfile with SSL. Ensure the sendfile fallback respects the chunk size."),
 	Transport = config(transport, Config),
 	Filename = config(filename, Config),
 	{ok, Binary} = file:read_file(Filename),
@@ -250,8 +239,7 @@ ssl_chunk_size(Config) ->
 		{ok, {Server, Client}} = sockets(Config),
 		{ok, RawFile} = file:open(Filename, [read, raw, binary]),
 		Ref = recv(Transport, Server, Size),
-		{ok, Size} = Transport:sendfile(Client, RawFile, 0, Size,
-				[{chunk_size, ChunkSize}]),
+		{ok, Size} = Transport:sendfile(Client, RawFile, 0, Size, [{chunk_size, ChunkSize}]),
 		{ok, Binary} = result(Ref),
 		{error, timeout} = Transport:recv(Server, 1, 100),
 		Self ! done,
diff --git a/test/shutdown_SUITE.erl b/test/shutdown_SUITE.erl
index 97963d5..212d14c 100644
--- a/test/shutdown_SUITE.erl
+++ b/test/shutdown_SUITE.erl
@@ -1,4 +1,4 @@
-%% Copyright (c) 2013, Loïc Hoguin <[email protected]>
+%% Copyright (c) 2013-2015, Loïc Hoguin <[email protected]>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -16,6 +16,7 @@
 -compile(export_all).
 
 -import(ct_helper, [doc/1]).
+-import(ct_helper, [name/0]).
 
 %% ct.
 
@@ -25,7 +26,8 @@ all() ->
 %% Tests.
 
 brutal_kill(_) ->
-	Name = brutal_kill,
+	doc("Shutdown Ranch listener with shutdown option set to brutal_kill."),
+	Name = name(),
 	{ok, ListenerSup} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{port, 0}, {shutdown, brutal_kill}],
 		echo_protocol, []),
@@ -33,8 +35,7 @@ brutal_kill(_) ->
 	{ok, _} = gen_tcp:connect("localhost", Port, []),
 	receive after 100 -> ok end,
 	ListenerSupChildren = supervisor:which_children(ListenerSup),
-	{_, ConnsSup, _, _}
-		= lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
+	{_, ConnsSup, _, _} = lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
 	[{_, Pid, _, _}] = supervisor:which_children(ConnsSup),
 	true = is_process_alive(Pid),
 	ok = ranch:stop_listener(Name),
@@ -45,7 +46,8 @@ brutal_kill(_) ->
 	ok.
 
 infinity(_) ->
-	Name = infinity,
+	doc("Shutdown Ranch listener with shutdown option set to infinity."),
+	Name = name(),
 	{ok, ListenerSup} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{port, 0}, {shutdown, infinity}],
 		echo_protocol, []),
@@ -53,8 +55,7 @@ infinity(_) ->
 	{ok, _} = gen_tcp:connect("localhost", Port, []),
 	receive after 100 -> ok end,
 	ListenerSupChildren = supervisor:which_children(ListenerSup),
-	{_, ConnsSup, _, _}
-		= lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
+	{_, ConnsSup, _, _} = lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
 	[{_, Pid, _, _}] = supervisor:which_children(ConnsSup),
 	true = is_process_alive(Pid),
 	ok = ranch:stop_listener(Name),
@@ -65,7 +66,10 @@ infinity(_) ->
 	ok.
 
 infinity_trap_exit(_) ->
-	Name = infinity_trap_exit,
+	doc("Shutdown Ranch listener with shutdown option set to infinity "
+		"and protocol process trapping exits. The listener must not stop "
+		"until the protocol process terminates."),
+	Name = name(),
 	{ok, ListenerSup} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{port, 0}, {shutdown, infinity}],
 		trap_exit_protocol, []),
@@ -73,8 +77,7 @@ infinity_trap_exit(_) ->
 	{ok, _} = gen_tcp:connect("localhost", Port, []),
 	receive after 100 -> ok end,
 	ListenerSupChildren = supervisor:which_children(ListenerSup),
-	{_, ConnsSup, _, _}
-		= lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
+	{_, ConnsSup, _, _} = lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
 	[{_, Pid, _, _}] = supervisor:which_children(ConnsSup),
 	true = is_process_alive(Pid),
 	%% This call will block infinitely.
@@ -93,9 +96,9 @@ infinity_trap_exit(_) ->
 	false = is_process_alive(SpawnPid),
 	ok.
 
-%% Same as infinity because the protocol doesn't trap exits.
 timeout(_) ->
-	Name = timeout,
+	doc("Shutdown Ranch listener with shutdown option set to 500ms."),
+	Name = name(),
 	{ok, ListenerSup} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{port, 0}, {shutdown, 500}],
 		echo_protocol, []),
@@ -103,8 +106,7 @@ timeout(_) ->
 	{ok, _} = gen_tcp:connect("localhost", Port, []),
 	receive after 100 -> ok end,
 	ListenerSupChildren = supervisor:which_children(ListenerSup),
-	{_, ConnsSup, _, _}
-		= lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
+	{_, ConnsSup, _, _} = lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
 	[{_, Pid, _, _}] = supervisor:which_children(ConnsSup),
 	true = is_process_alive(Pid),
 	ok = ranch:stop_listener(Name),
@@ -115,7 +117,10 @@ timeout(_) ->
 	ok.
 
 timeout_trap_exit(_) ->
-	Name = timeout_trap_exit,
+	doc("Shutdown Ranch listener with shutdown option set to 500ms "
+		"and protocol process trapping exits. The listener will only stop "
+		"after the 500ms timeout."),
+	Name = name(),
 	{ok, ListenerSup} = ranch:start_listener(Name, 1,
 		ranch_tcp, [{port, 0}, {shutdown, 500}],
 		trap_exit_protocol, []),
@@ -123,8 +128,7 @@ timeout_trap_exit(_) ->
 	{ok, _} = gen_tcp:connect("localhost", Port, []),
 	receive after 100 -> ok end,
 	ListenerSupChildren = supervisor:which_children(ListenerSup),
-	{_, ConnsSup, _, _}
-		= lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
+	{_, ConnsSup, _, _} = lists:keyfind(ranch_conns_sup, 1, ListenerSupChildren),
 	[{_, Pid, _, _}] = supervisor:which_children(ConnsSup),
 	true = is_process_alive(Pid),
 	%% This call will block for the duration of the shutdown.