src/estap.erl

   1 %%%---------------------------------------------------------------------------
   2 %%% @doc
   3 %%%   Functions to use in test cases.
   4 %%%
   5 %%%   Test passes if it returns or throws (`throw()'): `ok', `{ok, Value}', or
   6 %%%   `true'.
   7 %%%
   8 %%%   Test fails if it returns or throws `error', `{error, Reason}', `false',
   9 %%%   or calls `exit(...)' or `erlang:error(...)' (or simply dies).
  10 %%%
  11 %%%   Any other returned value is also considered a failure, but a dubious
  12 %%%   one. Stick to saying explicitly that the test failed.
  13 %%%
  14 %%%   All test functions return the value they were passed (an exception to
  15 %%%   this rule are {@link pass/1} and {@link fail/1} functions, for obvious
  16 %%%   reason). This allows test to be added around preparation function call
  17 %%%   for more complex test cases.
  18 %%% @end
  19 %%%---------------------------------------------------------------------------
  20
  21 -module(estap).
  22
  23 %% public interface
  24 -export([ok/2, pass/1, fail/1, is/3, isnt/3, eq/3, ne/3, cmp/4]).
  25 -export([like/3, unlike/3, matches/3]).
  26 -export([bail_out/1, no_plan/0, plan/1, all_ok/0]).
  27 -export([diag/1, diag/2, info/1, info/2, explain/1]).
  28 -export([test_dir/0, test_dir/1]).
  29
  30 -export_type([value/0, cmp/0, regexp/0, match_fun/0]).
  31
  32 %%%---------------------------------------------------------------------------
  33 %%% types {{{
  34
  35 -type value() :: term().
  36
  37 -type cmp() :: '<' | '>' | '=<' | '>=' | '/=' | '=/=' | '==' | '=:='.
  38
  39 -type regexp() :: iolist().
  40
  41 -type match_fun() :: fun((value()) -> any()).
  42
  43 -type message() :: iolist().
  44
  45 -type description() :: iolist().
  46
  47 -type info() :: atom() | iolist() |
  48                 {FieldName :: atom() | iolist(), Value :: atom() | iolist()}.
  49
  50 %%% }}}
  51 %%%---------------------------------------------------------------------------
  52 %%% public interface
  53 %%%---------------------------------------------------------------------------
  54
  55 %% @doc Check if `Value' is any of the recognized truth values.
  56
  57 -spec ok(value(), description()) ->
  58   Value :: value().
  59
  60 ok(Value, Description) ->
  61   TestRun = get_test_run(),
  62   estap_server:running(TestRun, Description),
  63   estap_server:report_result(TestRun, estap_test:success_or_failure(Value)),
  64   Value.
  65
  66 %% @doc Mark the test as a success unconditionally.
  67
  68 -spec pass(description()) ->
  69   true.
  70
  71 pass(Description) ->
  72   ok(true, Description).
  73
  74 %% @doc Mark the test as a failure unconditionally.
  75
  76 -spec fail(description()) ->
  77   false.
  78
  79 fail(Description) ->
  80   ok(false, Description).
  81
  82 %% @doc Check if `Value' is the same as `Expected'.
  83
  84 -spec is(value(), value(), description()) ->
  85   Value :: value().
  86
  87 is(Value, Expected, Description) ->
  88   case Value of
  89     Expected -> pass(Description);
  90     _ -> fail(Description)
  91   end,
  92   Value.
  93
  94 %% @doc Check if `Value' is different than `Expected'.
  95
  96 -spec isnt(value(), value(), description()) ->
  97   Value :: value().
  98
  99 isnt(Value, Expected, Description) ->
 100   case Value of
 101     Expected -> fail(Description);
 102     _ -> pass(Description)
 103   end,
 104   Value.
 105
 106 %% @doc Check if `Value' is equal (`==') to `Expected'.
 107
 108 -spec eq(value(), value(), description()) ->
 109   Value :: value().
 110
 111 eq(Value, Expected, Description) ->
 112   cmp(Value, '==', Expected, Description).
 113
 114 %% @doc Check if `Value' is not equal (`/=') to `Expected'.
 115
 116 -spec ne(value(), value(), description()) ->
 117   Value :: value().
 118
 119 ne(Value, Expected, Description) ->
 120   cmp(Value, '/=', Expected, Description).
 121
 122 %% @doc Compare `Value' and `Expected' using comparison operator.
 123
 124 -spec cmp(value(), cmp(), value(), description()) ->
 125   Value :: value().
 126
 127 cmp(Value, Cmp, Expected, Description) ->
 128   CmpResult = case Cmp of
 129     '<'   -> Value <   Expected;
 130     '>'   -> Value >   Expected;
 131     '=<'  -> Value =<  Expected;
 132     '>='  -> Value >=  Expected;
 133     '/='  -> Value /=  Expected;
 134     '=/=' -> Value =/= Expected;
 135     '=='  -> Value ==  Expected;
 136     '=:=' -> Value =:= Expected
 137   end,
 138   ok(CmpResult, Description),
 139   Value.
 140
 141 %% @doc Check if `Value' matches a regexp.
 142
 143 -spec like(value(), regexp(), description()) ->
 144   Value :: value().
 145
 146 like(Value, Expected, Description) ->
 147   % XXX: regular expression may be invalid, so prepare estap_server before
 148   % running the regexp
 149   TestRun = get_test_run(),
 150   estap_server:running(TestRun, Description),
 151   case re:run(Value, Expected) of
 152     {match, _Capture} -> estap_server:report_result(TestRun, {success, true});
 153     nomatch           -> estap_server:report_result(TestRun, {failure, false})
 154   end,
 155   Value.
 156
 157 %% @doc Check if `Value' not matches a regexp.
 158
 159 -spec unlike(value(), regexp(), description()) ->
 160   Value :: value().
 161
 162 unlike(Value, Expected, Description) ->
 163   % XXX: regular expression may be invalid, so prepare estap_server before
 164   % running the regexp
 165   TestRun = get_test_run(),
 166   estap_server:running(TestRun, Description),
 167   case re:run(Value, Expected) of
 168     {match, _Capture} -> estap_server:report_result(TestRun, {failure, false});
 169     nomatch           -> estap_server:report_result(TestRun, {success, true})
 170   end,
 171   Value.
 172
 173 %% @doc Check if `Value' pattern-matches.
 174 %%   Pattern is specified as a fun that has clauses defined only for what
 175 %%   should match, i.e., calling the fun should fail with `function_clause'
 176 %%   error. Return value of the fun is ignored.
 177
 178 -spec matches(value(), match_fun(), description()) ->
 179   Value :: value().
 180
 181 matches(Value, MatchSpec, Description) ->
 182   TestRun = get_test_run(),
 183   estap_server:running(TestRun, Description),
 184   try
 185     MatchSpec(Value),
 186     estap_server:report_result(TestRun, {success, true})
 187   catch
 188     error:function_clause ->
 189       estap_server:report_result(TestRun, {failure, false})
 190   end,
 191   Value.
 192
 193 %%%---------------------------------------------------------------------------
 194
 195 %% @doc Stop testing current suite because something terrible happened.
 196 %%
 197 %% @TODO Implement this function.
 198
 199 -spec bail_out(message()) ->
 200   no_return().
 201
 202 bail_out(_Message) ->
 203   'TODO'.
 204
 205 %% @doc Set the "no plan" plan for sub-tests.
 206 %%   Calling this function may be safely skipped.
 207 %%
 208 %% @see all_ok/0
 209
 210 -spec no_plan() ->
 211   ok.
 212
 213 no_plan() ->
 214   _TestRun = get_test_run(),
 215   ok.
 216
 217 %% @doc Set expected number of sub-tests.
 218
 219 -spec plan(pos_integer()) ->
 220   ok.
 221
 222 plan(TestCount) when is_integer(TestCount) ->
 223   TestRun = estap_server:subplan(TestCount, 1),
 224   set_test_run(TestRun),
 225   ok.
 226
 227 %% @doc Check if all the current sub-tests were OK.
 228 %%   Function intended to be called at the end of a sequence of sub-tests, to
 229 %%   indicate that the test sequence passed or failed.
 230
 231 -spec all_ok() ->
 232   true | false.
 233
 234 all_ok() ->
 235   TestRun = get_test_run(),
 236   {Planned, Total, Failed, _TODO} = estap_server:get_status(TestRun),
 237   estap_server:done(TestRun), % this ends estap_server, so it goes last
 238   (Failed == 0) and ((Planned == undefined) or (Planned == Total)).
 239
 240 %%%---------------------------------------------------------------------------
 241
 242 %% @doc Get a directory containing this test script.
 243 %%
 244 %%   <b>NOTE</b>: This function doesn't work in processes spawned from test
 245 %%   function. You need to get the directory in parent process and pass it as
 246 %%   an argument.
 247
 248 test_dir() ->
 249   case get(test_dir) of
 250     undefined -> erlang:error({undefined, test_dir});
 251     Directory -> Directory
 252   end.
 253
 254 %% @doc Get a subdirectory of the directory containing this test script.
 255 %%
 256 %%   <b>NOTE</b>: This function doesn't work in processes spawned from test
 257 %%   function. You need to get the directory in parent process and pass it as
 258 %%   an argument.
 259
 260 test_dir(Subdir) ->
 261   filename:join(test_dir(), Subdir).
 262
 263 %%%---------------------------------------------------------------------------
 264
 265 %% @doc Print a diagnostic message.
 266 %%   Typically, diagnostic message is a warning, but may be notice important
 267 %%   enough to print it along with test progress by TAP consumer.
 268 %%
 269 %%   Before first call to {@link plan/1}, {@link no_plan/0} or test functions
 270 %%   ({@link ok/2}, {@link is/3} etc.) message is printed at the level of
 271 %%   parent test. After any of those, it's printed at sub-test level.
 272 %%
 273 %%   Normally diagnostic output goes to <i>STDERR</i>, but under TODO tests it
 274 %%   goes to <i>STDOUT</i>.
 275 %%
 276 %% @TODO Make the diagnostic output go to <i>STDOUT</i> under TODO
 277
 278 -spec diag(message()) ->
 279   ok.
 280
 281 diag(Message) ->
 282   TestRun = get_test_run_or_parent(),
 283   estap_server:warning(TestRun, Message).
 284
 285 %% @doc Print a warning with some context.
 286 %%   Typically, diagnostic message is a warning, but may be notice important
 287 %%   enough to print it along with test progress by TAP consumer.
 288 %%
 289 %%   Before first call to {@link plan/1}, {@link no_plan/0} or test functions
 290 %%   ({@link ok/2}, {@link is/3} etc.) message is printed at the level of
 291 %%   parent test. After any of those, it's printed at sub-test level.
 292 %%
 293 %%   Normally diagnostic output goes to <i>STDERR</i>, but under TODO tests it
 294 %%   goes to <i>STDOUT</i>.
 295 %%
 296 %% @TODO Make the diagnostic output go to <i>STDOUT</i> under TODO
 297
 298 -spec diag(message(), [info()]) ->
 299   ok.
 300
 301 diag(Message, Info) ->
 302   TestRun = get_test_run_or_parent(),
 303   InfoLines = [["  ", format_info(I), "\n"] || I <- Info],
 304   estap_server:warning(TestRun, [Message, "\n", InfoLines]).
 305
 306 %% @doc Print a message.
 307 %%
 308 %%   Before first call to {@link plan/1}, {@link no_plan/0} or test functions
 309 %%   ({@link ok/2}, {@link is/3} etc.) message is printed at the level of
 310 %%   parent test. After any of those, it's printed at sub-test level.
 311
 312 -spec info(message()) ->
 313   ok.
 314
 315 info(Message) ->
 316   TestRun = get_test_run_or_parent(),
 317   estap_server:info(TestRun, Message).
 318
 319 %% @doc Print a message with some context.
 320 %%
 321 %%   Before first call to {@link plan/1}, {@link no_plan/0} or test functions
 322 %%   ({@link ok/2}, {@link is/3} etc.) message is printed at the level of
 323 %%   parent test. After any of those, it's printed at sub-test level.
 324
 325 -spec info(message(), [info()]) ->
 326   ok.
 327
 328 info(Message, Info) ->
 329   TestRun = get_test_run_or_parent(),
 330   InfoLines = [["  ", format_info(I), "\n"] || I <- Info],
 331   estap_server:info(TestRun, [Message, "\n", InfoLines]).
 332
 333 %% @doc Format a single info entry for printing it on screen.
 334
 335 -spec format_info(info()) ->
 336   binary().
 337
 338 format_info(Info) when is_list(Info); is_binary(Info) ->
 339   iolist_to_binary(Info);
 340 format_info(Info) when is_atom(Info) ->
 341   atom_to_binary(Info, unicode);
 342 format_info({K, V} = _Info) ->
 343   <<(format_info(K))/binary, ": ", (format_info(V))/binary>>.
 344
 345 %% @doc Format term so it can be printed to screen.
 346 %%   Convenience wrapper for {@link io_lib:format/2}.
 347 %%
 348 %% @see info/2
 349 %% @see diag/2
 350
 351 -spec explain(term()) ->
 352   iolist().
 353
 354 explain(Term) ->
 355   % no term should weigh 1MB
 356   io_lib:print(Term, 1, 1024 * 1024, -1).
 357
 358 %%%---------------------------------------------------------------------------
 359
 360 %% @doc Set previously started {@link estap_server}.
 361
 362 set_test_run(TestRun) ->
 363   put(estap_server, TestRun).
 364
 365 %% @doc Get associated {@link estap_server}, starting it if necessary.
 366
 367 get_test_run() ->
 368   case get(estap_server) of
 369     undefined ->
 370       TestRun = estap_server:subplan(no_plan, 1),
 371       put(estap_server, TestRun),
 372       TestRun;
 373     TestRun when is_pid(TestRun) ->
 374       TestRun
 375   end.
 376
 377 %% @doc Get associated {@link estap_server} or parent one if none is started
 378 %%   yet. Necessary for top-level {@link info/1} and {@link diag/1} to work.
 379
 380 get_test_run_or_parent() ->
 381   case get(estap_server) of
 382     undefined ->
 383       % XXX: this must be set in `estap_test:run()'
 384       get(estap_server_parent);
 385     TestRun when is_pid(TestRun) ->
 386       TestRun
 387   end.
 388
 389 %%%---------------------------------------------------------------------------
 390 %%% vim:ft=erlang:foldmethod=marker