Docs improvement: Testing with references to DataCase & DBConnection.OwnershipError
- Dominant language
- Elixir
- Stars
- 2.5k
- Forks
- 422
- Avg merge
- 23h 26m
- Merged PRs (30d)
- 46
Description
### Code of Conduct
- [x] I agree to follow this project's Code of Conduct
### AI Policy
- [x] I agree to follow this project's AI Policy, or I agree that AI was not used while creating this issue.
### Is your feature request related to a problem? Please describe.
See [this discussion](https://elixirforum.com/t/testing-in-ash-dbconnection-ownershiperror-cannot-find-ownership-process-for-pid/71883) for full context.
While getting a test harness up and running in a new Ash project, I ran into a few hiccups. I think some enhanced documentation would be well worth the investment.
I went back to look at the [Ash Test Resources how-to-guide](https://hexdocs.pm/ash/test-resources.html). It’s simplified (ETS) but, only shows how to use ExUnit.Case:
```
defmodule ActionInvocationTest do
use ExUnit.Case
...
```
And then there’s the section in [Ash Testing](https://hexdocs.pm/ash/testing.html#async-tests), which talks about about turning off `async?` during testing, which is helpful information but... lacked a bit of context (e.g., when does it really matter, as I was using Postgres I actually did *not* want to turn it off).
The issue I ran into was, specifically, that most (all?) of the examples used ETS and `ExUnit.Case`. Nowhere have I found mention of using DataCase. It may be in there, and for someone that uses Ecto a lot, it may be obvious – but it’s not on those two central documents about testing. Might make sense to add it?
In my case, ultimately realizing I should be using `DataCase` led to instant fixes:
1. Failing tests started passing (`DBConnection.OwnershipError` went away, this was hard to track down).
2. My ExUnit driven `doctests` started working just fine.
### Describe the solution you'd like
Would be great to:
1. Update docs with examples / highlights on use of `DataCase`.
2. Include relevant references to Ecto sources.
3. Mention that not using `DataCase` may likely run you into `DBConnection.OwnershipError` errors cascading all over the place. And break any `doctests`.
### Describe alternatives you've considered
_No response_
### Additional context
_No response_
Contributor guide
Research direction
Start with the Ash Test Resources how-to-guide and the Ash Testing async-tests section linked in the issue, comparing their ExUnit.Case examples with the requested DataCase usage. Check the relevant Ecto references and the documented DBConnection.OwnershipError and doctest behavior. Done means the central testing docs include DataCase examples, context for async tests, and these warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- elixir, postgresql
- Domain
- documentation, testing
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100