Rename bundle/2 to describe/2

Author: José Valim

CHANGELOG.md

@@ -136,7 +136,7 @@ plug
 Mix also includes `mix escript.install` and `mix escript.uninstall` tasks for managing escripts. The tasks was designed in a way to mimic the existing `mix archive` functionality except that:
 
   * Archives must be used sparingly because every new archive installed affects Mix performance, as every new archive is loaded when Mix boots. Escripts solve this by being managed apart from your Elixir/Mix installed
-  * Archives depends on the current Elixir version. Therefore, updating your Elixir version may break an archive. Fortunately, escripts bundle Elixir inside themselves, and therefore do not depend on your Elixir system version
+  * Archives depends on the current Elixir version. Therefore, updating your Elixir version may break an archive. Fortunately, escripts include Elixir inside themselves, and therefore do not depend on your Elixir system version
 
 Escripts will be installed at `~/.mix/escripts` which must be added to your [`PATH` environment variable](https://en.wikipedia.org/wiki/PATH_(variable)).
 
@@ -214,15 +214,15 @@ At the end of the run, ExUnit will also report it as a property, including both
 1 property, 10 tests, 0 failures
 ```
 
-### Named setups and bundles
+### Named setups and describes
 
-Finally, ExUnit v1.3 includes the ability to organize tests together in bundles:
+Finally, ExUnit v1.3 includes the ability to organize tests together in describe blocks:
 
 ```elixir
 defmodule StringTest do
   use ExUnit.Case, async: true
 
-  bundle "String.capitalize/2" do
+  describe "String.capitalize/2" do
     test "uppercases the first grapheme" do
       assert "T" <> _ = String.capitalize("test")
     end
@@ -234,25 +234,25 @@ defmodule StringTest do
 end
 ```
 
-Every test inside a bundle will be tagged with the bundle name. This allows developers to run tests that belong to particular bundles, be them in the same file or across many files:
+Every test inside a describe block will be tagged with the describe block name. This allows developers to run tests that belong to particular blocks, be them in the same file or across many files:
 
 ```
-$ mix test --only bundle:"String.capitalize/2"
+$ mix test --only describe:"String.capitalize/2"
 ```
 
-Note bundles cannot be nested. Instead of relying on hierarchy for composition, we want developers to build on top of named setups. For example:
+Note describe blocks cannot be nested. Instead of relying on hierarchy for composition, we want developers to build on top of named setups. For example:
 
 ```elixir
 defmodule UserManagementTest do
   use ExUnit.Case, async: true
 
-  bundle "when user is logged in and is an admin" do
+  describe "when user is logged in and is an admin" do
     setup [:log_user_in, :set_type_to_admin]
 
     test ...
   end
 
-  bundle "when user is logged in and is a manager" do
+  describe "when user is logged in and is a manager" do
     setup [:log_user_in, :set_type_to_manager]
 
     test ...
@@ -264,7 +264,7 @@ defmodule UserManagementTest do
 end
 ```
 
-By forbidding hierarchies in favor of named setups, it is straight-forward for the developer to glance at each bundle and know exactly the setup steps involved.
+By forbidding hierarchies in favor of named setups, it is straight-forward for the developer to glance at each describe block and know exactly the setup steps involved.
 
 ## v1.3.0-dev
 
@@ -320,7 +320,7 @@ By forbidding hierarchies in favor of named setups, it is straight-forward for t
   * [ExUnit] Raise a straight-forward error message in case a duplicate test name is defined
   * [ExUnit] Bump the default number of max cases to double of schedulers to support both IO and CPU bound tests
   * [ExUnit] Support for named setups in `setup` and `setup_all`
-  * [ExUnit] Support for bundling tests together with `bundle/2`
+  * [ExUnit] Support for bundling tests together with `describe/2`
 
 #### IEx
 

lib/elixir/src/elixir_utils.erl

@@ -230,7 +230,7 @@ convert_to_boolean(Line, Expr, Bool, S) when is_integer(Line) ->
     _               -> do_convert_to_boolean(Line, Expr, Bool, S)
   end.
 
-%% Notice we use a temporary var and bundle nil
+%% Notice we use a temporary var and include nil
 %% and false checks in the same clause since
 %% it makes dialyzer happy.
 do_convert_to_boolean(Line, Expr, Bool, S) ->

lib/ex_unit/lib/ex_unit/callbacks.ex

@@ -95,7 +95,7 @@ defmodule ExUnit.Callbacks do
   @doc false
   defmacro __using__(_) do
     quote do
-      @ex_unit_bundle nil
+      @ex_unit_describe nil
       @ex_unit_setup []
       @ex_unit_setup_all []
 
@@ -123,7 +123,7 @@ defmodule ExUnit.Callbacks do
       do_setup(quote(do: _), block)
     else
       quote do
-        @ex_unit_setup ExUnit.Callbacks.__callback__(unquote(block), @ex_unit_bundle) ++
+        @ex_unit_setup ExUnit.Callbacks.__callback__(unquote(block), @ex_unit_describe) ++
                        @ex_unit_setup
       end
     end
@@ -147,7 +147,7 @@ defmodule ExUnit.Callbacks do
     quote bind_quoted: [var: escape(var), block: escape(block)] do
       name = :"__ex_unit_setup_#{length(@ex_unit_setup)}"
       defp unquote(name)(unquote(var)), unquote(block)
-      @ex_unit_setup [{name, @ex_unit_bundle} | @ex_unit_setup]
+      @ex_unit_setup [{name, @ex_unit_describe} | @ex_unit_setup]
     end
   end
 
@@ -164,7 +164,8 @@ defmodule ExUnit.Callbacks do
       do_setup_all(quote(do: _), block)
     else
       quote do
-        @ex_unit_bundle && raise "cannot invoke setup_all/1 inside bundle"
+        @ex_unit_describe && raise "cannot invoke setup_all/1 inside describe as setup_all/1 " <>
+                                   "always applies to all tests in a module"
         @ex_unit_setup_all ExUnit.Callbacks.__callback__(unquote(block), nil) ++
                            @ex_unit_setup_all
       end
@@ -187,7 +188,7 @@ defmodule ExUnit.Callbacks do
 
   defp do_setup_all(var, block) do
     quote bind_quoted: [var: escape(var), block: escape(block)] do
-      @ex_unit_bundle && raise "cannot invoke setup_all/2 inside bundle"
+      @ex_unit_describe && raise "cannot invoke setup_all/2 inside describe"
       name = :"__ex_unit_setup_all_#{length(@ex_unit_setup_all)}"
       defp unquote(name)(unquote(var)), unquote(block)
       @ex_unit_setup_all [{name, nil} | @ex_unit_setup_all]
@@ -216,17 +217,17 @@ defmodule ExUnit.Callbacks do
 
   ## Helpers
 
-  @reserved [:case, :file, :line, :test, :async, :registered, :bundle]
+  @reserved [:case, :file, :line, :test, :async, :registered, :describe]
 
   @doc false
-  def __callback__(callback, bundle) do
+  def __callback__(callback, describe) do
     for k <- List.wrap(callback) do
       if not is_atom(k) do
         raise ArgumentError, "setup/setup_all expect a callback name as an atom or " <>
                              "a list of callback names, got: #{inspect k}"
       end
 
-      {k, bundle}
+      {k, describe}
     end |> Enum.reverse()
   end
 
@@ -287,17 +288,17 @@ defmodule ExUnit.Callbacks do
         [] ->
           quote do: context
         [h | t] ->
-          Enum.reduce t, compile_merge(h), fn callback_bundle, acc ->
+          Enum.reduce t, compile_merge(h), fn callback_describe, acc ->
             quote do
               context = unquote(acc)
-              unquote(compile_merge(callback_bundle))
+              unquote(compile_merge(callback_describe))
             end
           end
       end
 
     quote do
       def __ex_unit__(unquote(kind), context) do
-        bundle = Map.get(context, :bundle, nil)
+        describe = Map.get(context, :describe, nil)
         unquote(acc)
       end
     end
@@ -309,9 +310,9 @@ defmodule ExUnit.Callbacks do
     end
   end
 
-  defp compile_merge({callback, bundle}) do
+  defp compile_merge({callback, describe}) do
     quote do
-      if unquote(bundle) == bundle do
+      if unquote(describe) == describe do
         unquote(compile_merge({callback, nil}))
       else
         context

lib/ex_unit/lib/ex_unit/case.ex

@@ -125,7 +125,7 @@ defmodule ExUnit.Case do
     * `:async`      - if the test case is in async mode
     * `:type`       - the type of the test (`:test`, `:property`, etc)
     * `:registered` - used for `ExUnit.Case.register_attribute/3` values
-    * `:bundle`     - the bundle the test belongs to
+    * `:describe`   - the describe block the test belongs to
 
   The following tags customize how tests behaves:
 
@@ -190,7 +190,7 @@ defmodule ExUnit.Case do
       config :logger, backends: []
   """
 
-  @reserved [:case, :file, :line, :test, :async, :registered, :bundle, :type]
+  @reserved [:case, :file, :line, :test, :async, :registered, :describe, :type]
 
   @doc false
   defmacro __using__(opts) do
@@ -203,19 +203,19 @@ defmodule ExUnit.Case do
       async = !!unquote(opts)[:async]
 
       unless Module.get_attribute(__MODULE__, :ex_unit_tests) do
-        Enum.each [:ex_unit_tests, :tag, :bundletag, :moduletag, :ex_unit_registered],
+        Enum.each [:ex_unit_tests, :tag, :describetag, :moduletag, :ex_unit_registered],
           &Module.register_attribute(__MODULE__, &1, accumulate: true)
 
         @before_compile ExUnit.Case
         @after_compile ExUnit.Case
         @ex_unit_async async
-        @ex_unit_bundle nil
+        @ex_unit_describe nil
         use ExUnit.Callbacks
       end
 
       import ExUnit.Callbacks
       import ExUnit.Assertions
-      import ExUnit.Case, only: [bundle: 2, test: 1, test: 2, test: 3]
+      import ExUnit.Case, only: [describe: 2, test: 1, test: 2, test: 3]
       import ExUnit.DocTest
     end
   end
@@ -283,20 +283,20 @@ defmodule ExUnit.Case do
   end
 
   @doc """
-  Bundles tests together.
+  Describes tests together.
 
-  Every bundle receives a name which is used as prefix for upcoming tests.
-  Inside a bundle, `ExUnit.Callbacks.setup/1` may be invoked and it will
-  define a setup callback to run only for the current bundle. The bundle
-  name is also added as a tag, allowing developers to run tests for
-  specific bundles.
+  Every describe block receives a name which is used as prefix for
+  upcoming tests. Inside a block, `ExUnit.Callbacks.setup/1` may be
+  invoked and it will define a setup callback to run only for the
+  current block. The describe name is also added as a tag, allowing
+  developers to run tests for specific blocks.
 
   ## Examples
 
       defmodule StringTest do
         use ExUnit.Case, async: true
 
-        bundle "String.capitalize/1" do
+        describe "String.capitalize/1" do
           test "first grapheme is in uppercase" do
             assert String.capitalize("hello") == "Hello"
           end
@@ -307,28 +307,56 @@ defmodule ExUnit.Case do
         end
       end
 
-  When using Mix, you can run all tests in a bundle as:
+  When using Mix, you can run all tests in a describe block as:
 
-      mix test --only bundle:"String.capitalize/1"
+      mix test --only describe:"String.capitalize/1"
 
+  Note describe blocks cannot be nested. Instead of relying on hierarchy
+  for composition, developers should build on top of named setups. For
+  example:
+
+      defmodule UserManagementTest do
+        use ExUnit.Case, async: true
+
+        describe "when user is logged in and is an admin" do
+          setup [:log_user_in, :set_type_to_admin]
+
+          test ...
+        end
+
+        describe "when user is logged in and is a manager" do
+          setup [:log_user_in, :set_type_to_manager]
+
+          test ...
+        end
+
+        defp log_user_in(context) do
+          # ...
+        end
+      end
+
+  By forbidding hierarchies in favor of named setups, it is straight-forward
+  for the developer to glance at each describe block and know exactly the
+  setup steps involved.
   """
-  defmacro bundle(message, do: block) do
+  defmacro describe(message, do: block) do
     quote do
-      if @ex_unit_bundle do
-        raise "cannot call bundle/2 inside another bundle"
+      if @ex_unit_describe do
+        raise "cannot call describe/2 inside another describe. See the documentation " <>
+              "for describe/2 on named setups and how to handle hierarchies"
       end
 
-      @ex_unit_bundle (case unquote(message) do
+      @ex_unit_describe (case unquote(message) do
         msg when is_binary(msg) -> msg
-        msg -> raise ArgumentError, "bundle name must be a string, got: #{inspect msg}"
+        msg -> raise ArgumentError, "describe name must be a string, got: #{inspect msg}"
       end)
-      Module.delete_attribute(__ENV__.module, :bundletag)
+      Module.delete_attribute(__ENV__.module, :describetag)
 
       try do
         unquote(block)
       after
-        @ex_unit_bundle nil
-        Module.delete_attribute(__ENV__.module, :bundletag)
+        @ex_unit_describe nil
+        Module.delete_attribute(__ENV__.module, :describetag)
       end
     end
   end
@@ -377,9 +405,9 @@ defmodule ExUnit.Case do
     tag = Module.get_attribute(mod, :tag)
     async = Module.get_attribute(mod, :ex_unit_async)
 
-    {name, bundle, bundletag} =
-      if bundle = Module.get_attribute(mod, :ex_unit_bundle) do
-        {:"#{type} #{bundle} #{name}", bundle, Module.get_attribute(mod, :bundletag)}
+    {name, describe, describetag} =
+      if describe = Module.get_attribute(mod, :ex_unit_describe) do
+        {:"#{type} #{describe} #{name}", describe, Module.get_attribute(mod, :describetag)}
       else
         {:"#{type} #{name}", nil, []}
       end
@@ -389,11 +417,11 @@ defmodule ExUnit.Case do
     end
 
     tags =
-      (tags ++ tag ++ bundletag ++ moduletag)
+      (tags ++ tag ++ describetag ++ moduletag)
       |> normalize_tags
       |> validate_tags
       |> Map.merge(%{line: line, file: file, registered: registered,
-                     async: async, bundle: bundle, type: type})
+                     async: async, describe: describe, type: type})
 
     test = %ExUnit.Test{name: name, case: mod, tags: tags}
     Module.put_attribute(mod, :ex_unit_tests, test)