Repository: elixir-ecto/ecto
Pull request #2466 (2018-03-17 10:27:53)

Chapter for Test Environment Setup
https://github.com/elixir-ecto/ecto/issues/2465

ebert[bot]: Hello, @philippneugebauer! This is your first Pull Request that will be reviewed by [Ebert](https://ebertapp.io/), an automatic Code Review service. It will leave comments on this diff with potential issues and style violations found in the code as you push new commits. You can also see all the issues found on this Pull Request on its [review page](https://ebertapp.io/github/elixir-ecto/ecto/pulls/2466). Please check our [documentation](https://docs.ebertapp.io) for more information. 
philippneugebauer: @josevalim I've added the chapter
philippneugebauer: Should the `aliases` function for the `test` command also be included? I am not sure about that.
josevalim: Thanks @philippneugebauer! I have done some changes that expand a bit more the point of using the sandbox. Can you please review my changes?

I think we should also mention the aliases in mix.exs because it makes running tests more convenient, could you please add that too?

Thanks!
philippneugebauer: I have also added the `aliases`. Should be good to merge now

Patch:
diff --git a/guides/Getting Started.md b/guides/Getting Started.md
index 47eb0214..583fd8f4 100644
--- a/guides/Getting Started.md
+++ b/guides/Getting Started.md
@@ -119,6 +119,10 @@ This tells our application about the repo, which will allow us to run commands s
 
 We've now configured our application so that it's able to make queries to our database. Let's now create our database, add a table to it, and then perform some queries.
 
+## Test Environment Setup
+
+The test environment setup is described [here](Testing%20with%20Ecto.md).
+
 ## Setting up the database
 
 To be able to query a database, it first needs to exist. We can create the database with this command:


Test patch:
diff --git a/guides/Testing with Ecto.md b/guides/Testing with Ecto.md
new file mode 100644
index 00000000..56437a08
--- /dev/null
+++ b/guides/Testing with Ecto.md
@@ -0,0 +1,106 @@
+# Testing with Ecto
+
+After you have successfully set up your database connection with Ecto for your application,
+its usage for your tests requires further changes, especially if you want to leverage the
+Ecto SQL Sandbox that allows you to run tests that talk to the database concurrently.
+
+Create the `config/test.exs` file or append the following content:
+
+```elixir
+use Mix.Config
+
+config :my_app, MyApp.Repo,
+  adapter: Ecto.Adapters.Postgres,
+  username: "postgres",
+  password: "postgres",
+  database: "myapp_test",
+  hostname: "localhost",
+  pool: Ecto.Adapters.SQL.Sandbox
+ 
+ ```
+ 
+Thereby, we configure the database connection for our test setup.
+In this case, we use a Postgres database and set it up to use the sandbox pool that will wrap each test in a transaction.
+
+We also need to add an explicit statement to the end of `test/test_helper.exs` about the `sandbox` mode:
+
+```elixir
+Ecto.Adapters.SQL.Sandbox.mode(MyApp.Repo, :manual)
+```
+
+Lastly, you need to establish the database connection ahead of your tests.
+You can enable it either for all of your test cases by extending the `ExUnit` template or by setting it up individually for each test. Let's start with the former:
+
+```elixir
+defmodule MyApp.RepoCase do
+  use ExUnit.CaseTemplate
+
+  using do
+    quote do
+      alias MyApp.Repo
+
+      import Ecto
+      import Ecto.Query
+      import MyApp.RepoCase
+      
+      # and any other stuff
+    end
+  end
+
+  setup tags do
+    :ok = Ecto.Adapters.SQL.Sandbox.checkout(MyApp.Repo)
+    
+    unless tags[:async] do
+      Ecto.Adapters.SQL.Sandbox.mode(MyApp.Repo, {:shared, self()})
+    end
+    
+    :ok
+  end
+end
+```
+
+The case template above brings `Ecto` and `Ecto.Query` functions into your tests and checkouts a database connection. It also enables a shared sandbox connection mode in case the test is not running asynchronously. See `Ecto.Adapters.SQL.Sandbox` for more information.
+
+And then in each test that uses the repository:
+
+```elixir
+defmodule MyApp.MyTest do
+  use MyApp.RepoCase
+  
+  # Tests etc...
+end
+```
+
+In case you don't want to define a "case template", you can checkout on each individual case:
+
+```elixir
+defmodule MyApp.MyTest do
+  use ExUnit.Case
+
+  setup do
+    :ok = Ecto.Adapters.SQL.Sandbox.checkout(MyApp.Repo)
+  end
+  
+  # Tests etc...
+end
+```
+
+For convenience reasons, you can also define `aliases` to automatically set up your database at the execution of your tests.
+Change the following content in your `mix.exs`.
+
+```elixir
+
+  def project do
+    [app: :my_app,
+    
+     ...
+     
+     aliases: aliases()]
+  end
+  
+  defp aliases do
+    [ ...
+     "test": ["ecto.create --quiet", "ecto.migrate", "test"]
+    ]
+  end
+```