Improve use-fixtures docstring

Question

The docstring for use-fixtures says

Wrap test runs in a fixture function to perform setup and teardown. Using a fixture-type of :each wraps every test individually, while: once wraps the whole run in a single function

I think it would be helpful to explain what a fixture function is and how it performs setup and teardown. I know because I've looked at examples, but I don't think the docstring explains this at all.

Is this something Core is interested in taking a patch on?

Answer 1

Comment made by: alexmiller

It's explained in the clojure.test ns docstring in more depth:

`
Fixtures are attached to namespaces in one of two ways. \"each\"
fixtures are run repeatedly, once for each test function created
with \"deftest\" or \"with-test\". \"each\" fixtures are useful for
establishing a consistent before/after state for each test, like
clearing out database tables.

\"each\" fixtures can be attached to the current namespace like this:
(use-fixtures :each fixture1 fixture2 ...)
The fixture1, fixture2 are just functions like the example above.
They can also be anonymous functions, like this:
(use-fixtures :each (fn [f] setup... (f) cleanup...))

The other kind of fixture, a \"once\" fixture, is only run once,
around ALL the tests in the namespace. \"once\" fixtures are useful
for tasks that only need to be performed once, like establishing
database connections, or for time-consuming tasks.

Attach \"once\" fixtures to the current namespace like this:
(use-fixtures :once fixture1 fixture2 ...)
`

I'm not really answering your question, just wondering if you saw that and whether it changes your question.

Answer 2

Comment made by: desk@danielcompton.net

Perhaps just pointing the user towards the ns docstring would be a good alternative? I had forgotten about the docstring on the ns, and I'm not sure whether duplicating the docs about fixtures in use-fixtures is a great idea.

Perhaps something like this?

`
Wrap test runs in a fixture function to perform setup and teardown.
Using a fixture-type of :each wraps every test individually,
while :once wraps the whole run in a single function

See the clojure.test docstring for more details.
`

Answer 3

Reference: https://clojure.atlassian.net/browse/CLJ-1813 (reported by desk@danielcompton.net)