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.