diff --git a/lib/ex_unit/lib/ex_unit.ex b/lib/ex_unit/lib/ex_unit.ex index b323e0f58e5..4266fe9dc5d 100644 --- a/lib/ex_unit/lib/ex_unit.ex +++ b/lib/ex_unit/lib/ex_unit.ex @@ -328,7 +328,8 @@ defmodule ExUnit do defaults to `IO.ANSI.color_background(0, 2, 0)`; * `:exclude` - specifies which tests are run by skipping tests that match the - filter. See the "Filters" section in the documentation for `ExUnit.Case`; + filter. For more information, see the "Tags" and "Filters" sections in the + documentation for `ExUnit.Case`; * `:exit_status` - specifies an alternate exit status to use when the test suite fails. Defaults to `2`; @@ -342,8 +343,9 @@ defmodule ExUnit do * `:include` - specifies which tests are run by skipping tests that do not match the filter. Keep in mind that all tests are included by default, so unless they are excluded first, the `:include` option has no effect. To only run the tests - that match the `:include` filter, exclude the `:test` tag first (see the - documentation for `ExUnit.Case` for more information on tags and filters); + that match the `:include` filter, exclude the `:test` tag first. + For more information, see the "Tags" and "Filters" sections in the + documentation for `ExUnit.Case`; * `:max_cases` - maximum number of tests to run in parallel. Only tests from different modules run in parallel. It defaults to `System.schedulers_online * 2` diff --git a/lib/ex_unit/lib/ex_unit/case.ex b/lib/ex_unit/lib/ex_unit/case.ex index 6af10d22b3d..9e66fa5e180 100644 --- a/lib/ex_unit/lib/ex_unit/case.ex +++ b/lib/ex_unit/lib/ex_unit/case.ex @@ -196,6 +196,37 @@ defmodule ExUnit.Case do * `:tmp_dir` - (since v1.11.0) see the "Tmp Dir" section below + ## Filters + + Tags can also be used to identify specific tests, which can then + be included or excluded using filters. The most common functionality + is to exclude some particular tests from running, which can be done + via `ExUnit.configure/1`: + + # Exclude all external tests from running + ExUnit.configure(exclude: [external: true]) + + From now on, ExUnit will not run any test that has the `:external` option + set to `true`. This behaviour can be reversed with the `:include` option + which is usually passed through the command line: + + $ mix test --include external:true + + Run `mix help test` for more information on how to run filters via Mix. + + Another use case for tags and filters is to exclude all tests that have + a particular tag by default, regardless of its value, and include only + a certain subset: + + ExUnit.configure(exclude: :os, include: [os: :unix]) + + A given include/exclude filter can be given more than once: + + ExUnit.configure(exclude: [os: :unix, os: :windows]) + + Keep in mind that all tests are included by default, so unless they are + excluded first, the `include` option has no effect. + ## Parameterized tests Sometimes you want to run the same tests but with different parameters. @@ -231,37 +262,6 @@ defmodule ExUnit.Case do may be the wrong solution to your problem. Consider creating separated tests and sharing logic between them using regular functions - ## Filters - - Tags can also be used to identify specific tests, which can then - be included or excluded using filters. The most common functionality - is to exclude some particular tests from running, which can be done - via `ExUnit.configure/1`: - - # Exclude all external tests from running - ExUnit.configure(exclude: [external: true]) - - From now on, ExUnit will not run any test that has the `:external` option - set to `true`. This behaviour can be reversed with the `:include` option - which is usually passed through the command line: - - $ mix test --include external:true - - Run `mix help test` for more information on how to run filters via Mix. - - Another use case for tags and filters is to exclude all tests that have - a particular tag by default, regardless of its value, and include only - a certain subset: - - ExUnit.configure(exclude: :os, include: [os: :unix]) - - A given include/exclude filter can be given more than once: - - ExUnit.configure(exclude: [os: :unix, os: :windows]) - - Keep in mind that all tests are included by default, so unless they are - excluded first, the `include` option has no effect. - ## Log Capture ExUnit can optionally suppress printing of log messages that are generated