diff --git a/src/macros/test.md b/src/macros/test.md
index 30de8070..ec3cee90 100644
--- a/src/macros/test.md
+++ b/src/macros/test.md
@@ -1,6 +1,6 @@
Mark an `async fn` as a test with SQLx support.
-The test will automatically be executed in the async runtime according to the chosen
+The test will automatically be executed in the async runtime according to the chosen
`runtime-{async-std, tokio}` feature. If more than one runtime feature is enabled, `runtime-tokio` is preferred.
By default, this behaves identically to `#[tokio::test]`1 or `#[async_std::test]`:
@@ -31,25 +31,24 @@ but are isolated from each other.
This feature is activated by changing the signature of your test function. The following signatures are supported:
* `async fn(Pool) -> Ret`
- * the `Pool`s used by all running tests share a single connection limit to avoid exceeding the server's limit.
+ * the `Pool`s used by all running tests share a single connection limit to avoid exceeding the server's limit.
* `async fn(PoolConnection) -> Ret`
- * `PoolConnection`, etc.
+ * `PoolConnection`, etc.
* `async fn(PoolOptions, impl ConnectOptions) -> Ret`
* Where `impl ConnectOptions` is, e.g, `PgConnectOptions`, `MySqlConnectOptions`, etc.
- * If your test wants to create its own `Pool` (for example, to set pool callbacks or to modify `ConnectOptions`),
+ * If your test wants to create its own `Pool` (for example, to set pool callbacks or to modify `ConnectOptions`),
you can use this signature.
Where `DB` is a supported `Database` type and `Ret` is `()` or `Result<_, _>`.
##### Supported Databases
-Most of these will require you to set `DATABASE_URL` as an environment variable
+Most of these will require you to set `DATABASE_URL` as an environment variable
or in a `.env` file like `sqlx::query!()` _et al_, to give the test driver a superuser connection with which
to manage test databases.
-
| Database | Requires `DATABASE_URL` |
-| --- | --- |
+|----------|-------------------------|
| Postgres | Yes |
| MySQL | Yes |
| SQLite | No2 |
@@ -58,7 +57,7 @@ Test databases are automatically cleaned up as tests succeed, but failed tests w
to facilitate debugging. Note that to simplify the implementation, panics are _always_ considered to be failures,
even for `#[should_panic]` tests.
-To limit disk space usage, any previously created test databases will be deleted the next time a test binary using
+To limit disk space usage, any previously created test databases will be deleted the next time a test binary using
`#[sqlx::test]` is run.
```rust,no_run
@@ -86,8 +85,8 @@ converted to a filesystem path (`::` replaced with `/`).
### Automatic Migrations (requires `migrate` feature)
-To ensure a straightforward test implementation against a fresh test database, migrations are automatically applied if a
-`migrations` folder is found in the same directory as `CARGO_MANIFEST_DIR` (the directory where the current crate's
+To ensure a straightforward test implementation against a fresh test database, migrations are automatically applied if a
+`migrations` folder is found in the same directory as `CARGO_MANIFEST_DIR` (the directory where the current crate's
`Cargo.toml` resides).
You can override the resolved path relative to `CARGO_MANIFEST_DIR` in the attribute (global overrides are not currently
@@ -116,11 +115,13 @@ async fn basic_test(pool: PgPool) -> sqlx::Result<()> {
Or if you're already embedding migrations in your main crate, you can reference them directly:
`foo_crate/lib.rs`
+
```rust,ignore
pub static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("foo_migrations");
```
`foo_crate/tests/foo_test.rs`
+
```rust,no_run
# #[cfg(all(feature = "migrate", feature = "postgres"))]
# mod example {
@@ -129,12 +130,7 @@ use sqlx::{PgPool, Row};
# // This is standing in for the main crate since doc examples don't support multiple crates.
# mod foo_crate {
# use std::borrow::Cow;
-# static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate::Migrator {
-# migrations: Cow::Borrowed(&[]),
-# ignore_missing: false,
-# locking: true,
-# no_tx: false
-# };
+# static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate::Migrator::DEFAULT;
# }
// You could also do `use foo_crate::MIGRATOR` and just refer to it as `MIGRATOR` here.
@@ -188,9 +184,12 @@ the database to already have users and posts in it so the comments tests don't h
You can either pass a list of fixture to the attribute `fixtures` in three different operating modes:
-1) Pass a list of references files in `./fixtures` (resolved as `./fixtures/{name}.sql`, `.sql` added only if extension is missing);
-2) Pass a list of file paths (including associated extension), in which case they can either be absolute, or relative to the current file;
-3) Pass a `path = ` parameter and a `scripts(, , ...)` parameter that are relative to the provided path (resolved as `{path}/{filename_x}.sql`, `.sql` added only if extension is missing).
+1) Pass a list of references files in `./fixtures` (resolved as `./fixtures/{name}.sql`, `.sql` added only if extension
+ is missing);
+2) Pass a list of file paths (including associated extension), in which case they can either be absolute, or relative to
+ the current file;
+3) Pass a `path = ` parameter and a `scripts(, , ...)` parameter that are
+ relative to the provided path (resolved as `{path}/{filename_x}.sql`, `.sql` added only if extension is missing).
In any case they will be applied in the given order3:
@@ -225,6 +224,6 @@ async fn test_create_comment(pool: PgPool) -> sqlx::Result<()> {
Multiple `fixtures` attributes can be used to combine different operating modes.
3Ordering for test fixtures is entirely up to the application, and each test may choose which fixtures to
-apply and which to omit. However, since each fixture is applied separately (sent as a single command string, so wrapped
-in an implicit `BEGIN` and `COMMIT`), you will want to make sure to order the fixtures such that foreign key
+apply and which to omit. However, since each fixture is applied separately (sent as a single command string, so wrapped
+in an implicit `BEGIN` and `COMMIT`), you will want to make sure to order the fixtures such that foreign key
requirements are always satisfied, or else you might get errors.