From 9937369018b5d2ffe12055fff284f959b87ca242 Mon Sep 17 00:00:00 2001 From: Joe DeVivo Date: Wed, 3 Oct 2012 12:35:16 -0700 Subject: [PATCH] Added docs to rt --- src/rt.erl | 119 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 86 insertions(+), 33 deletions(-) diff --git a/src/rt.erl b/src/rt.erl index c473d72e..47d6875e 100644 --- a/src/rt.erl +++ b/src/rt.erl @@ -4,7 +4,6 @@ %% Please extend this module with new functions that prove useful between %% multiple independent tests. -module(rt). --compile(export_all). -include_lib("eunit/include/eunit.hrl"). -export([admin/2, @@ -60,6 +59,42 @@ -export([partition/2, heal/1]). +-export([ + update_app_config/2, + async_start/1, + slow_upgrade/3, + spawn_cmd/1, + wait_for_cmd/1, + cmd/1, + are_no_pending/1, + wait_for_service/2, + wait_for_cluster_service/2, + capability/2, + wait_until_capability/3, + rpc_get_env/2, + connection_info/1, + http_url/1, + systest_write/2, + systest_write/3, + systest_write/5, + systest_read/2, + systest_read/3, + systest_read/5, + pbc/1, + pbc_read/3, + pbc_write/4, + pbc_set_bucket_prop/3, + httpc/1, + httpc_read/3, + httpc_write/4, + pmap/2, + str/2, + set_backend/1, + get_version/0, + attach/2, + console/2 +]). + -define(HARNESS, (rt:config(rt_harness))). %% @doc Get the value of an OS Environment variable. The arity 1 version of @@ -161,6 +196,8 @@ join(Node, PNode) -> ?assertEqual(ok, R), ok. +%% @doc try_join tries different rpc:calls to join a node, because the module changed +%% in riak 1.2.0 try_join(Node, PNode) -> case rpc:call(Node, riak_core, join, [PNode]) of {badrpc, _} -> @@ -176,6 +213,8 @@ leave(Node) -> ?assertEqual(ok, R), ok. +%% @doc try_leave tries different rpc:calls to leave a node, because the module changed +%% in riak 1.2.0 try_leave(Node) -> case rpc:call(Node, riak_core, leave, []) of {badrpc, _} -> @@ -185,6 +224,7 @@ try_leave(Node) -> Result end. +%% @doc Call 'bin/riak-admin' command on node Node and arguments Args admin(Node, Args) -> ?HARNESS:admin(Node, Args). @@ -206,6 +246,8 @@ down(Node, OtherNode) -> rpc:call(Node, riak_kv_console, down, [[atom_to_list(OtherNode)]]). %% @doc partition the P1 from P2 nodes +%% note: the nodes remained connected to riak_test@local, +%% which is how heal/1 can still work. partition(P1, P2) -> OldCookie = rpc:call(hd(P1), erlang, get_cookie, []), NewCookie = list_to_atom(lists:reverse(atom_to_list(OldCookie))), @@ -245,6 +287,34 @@ check_singleton_node(Node) -> ?assertEqual([Node], Owners), ok. +%% @doc Utility function used to construct test predicates. Retries the +%% function `Fun' until it returns `true', or until the maximum +%% number of retries is reached. The retry limit is based on the +%% provided `rt_max_wait_time' and `rt_retry_delay' parameters in +%% specified `riak_test' config file. +wait_until(Node, Fun) -> + MaxTime = rt:config(rt_max_wait_time), + Delay = rt:config(rt_retry_delay), + Retry = MaxTime div Delay, + wait_until(Node, Fun, Retry, Delay). + +%% @deprecated Use {@link wait_until/2} instead. +wait_until(Node, Fun, Retry) -> + wait_until(Node, Fun, Retry, 500). + +%% @deprecated Use {@link wait_until/2} instead. +wait_until(Node, Fun, Retry, Delay) -> + Pass = Fun(Node), + case {Retry, Pass} of + {_, true} -> + ok; + {0, _} -> + fail; + _ -> + timer:sleep(Delay), + wait_until(Node, Fun, Retry-1) + end. + %% @doc Wait until the specified node is considered ready by `riak_core'. %% As of Riak 1.0, a node is ready if it is in the `valid' or `leaving' %% states. A ready node is guaranteed to have current preflist/ownership @@ -410,34 +480,6 @@ wait_until_unpingable(Node) -> ?assertEqual(ok, wait_until(Node, F)), ok. -%% @doc Utility function used to construct test predicates. Retries the -%% function `Fun' until it returns `true', or until the maximum -%% number of retries is reached. The retry limit is based on the -%% provided `rt_max_wait_time' and `rt_retry_delay' parameters in -%% specified `riak_test' config file. -wait_until(Node, Fun) -> - MaxTime = rt:config(rt_max_wait_time), - Delay = rt:config(rt_retry_delay), - Retry = MaxTime div Delay, - wait_until(Node, Fun, Retry, Delay). - -%% @deprecated Use {@link wait_until/2} instead. -wait_until(Node, Fun, Retry) -> - wait_until(Node, Fun, Retry, 500). - -%% @deprecated Use {@link wait_until/2} instead. -wait_until(Node, Fun, Retry, Delay) -> - Pass = Fun(Node), - case {Retry, Pass} of - {_, true} -> - ok; - {0, _} -> - fail; - _ -> - timer:sleep(Delay), - wait_until(Node, Fun, Retry-1) - end. - capability(Node, Capability) -> rpc:call(Node, riak_core_capability, get, [Capability]). @@ -556,9 +598,9 @@ build_cluster(NumNodes, Versions, InitialConfig) -> lager:info("Cluster built: ~p", [Nodes]), Nodes. -%% Helper that returns first successful application get_env result, -%% used when different versions of Riak use different app vars for -%% the same setting. +%% @doc Helper that returns first successful application get_env result, +%% used when different versions of Riak use different app vars for +%% the same setting. rpc_get_env(_, []) -> undefined; rpc_get_env(Node, [{App,Var}|Others]) -> @@ -673,7 +715,6 @@ httpc_read(C, Bucket, Key) -> {ok, Value} = rhc:get(C, Bucket, Key), Value. - %% @doc does a write via the http erlang client. -spec httpc_write(term(), binary(), binary(), binary()) -> atom(). httpc_write(C, Bucket, Key, Value) -> @@ -737,8 +778,20 @@ teardown() -> whats_up() -> ?HARNESS:whats_up(). +%% @doc Runs `riak attach' on a specific node, and tests for the expected behavoir. +%% Here's an example: +%% rt:attach(Node, [{expect, "erlang.pipe.1 \(^D to exit\)"}, +%% {send, "riak_core_ring_manager:get_my_ring()."}, +%% {expect, "dict,"}, +%% {send, [4]}]), %% 4 = Ctrl + D +%% {expect, String} scans the output for the existance of the String. +%% These tuples are processed in order. +%% {send, String} sends the string to the console. +%% Once a send is encountered, the buffer is discarded, and the next +%% expect will process based on the output following the sent data. attach(Node, Expected) -> ?HARNESS:attach(Node, Expected). +%% @doc Runs `riak console' on a specific node, see rt:attach/2 for more info. console(Node, Expected) -> ?HARNESS:console(Node, Expected).