itsscb/sqlx
1
0
Fork 0
mirror of https://github.com/launchbadge/sqlx.git synced 2025-12-29 21:00:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: doctest

Browse Source
This commit is contained in:
Austin Bonander 2025-03-30 19:21:19 -07:00
parent 0a32d01081
commit 1eb0f499b7
1 changed files with 20 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
src/macros/test.md
View File

@ -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]`<sup>1</sup> 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<DB>) -> 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<DB>) -> Ret`
* `PoolConnection<Postgres>`, etc.
* `PoolConnection<Postgres>`, etc.
* `async fn(PoolOptions<DB>, impl ConnectOptions<DB>) -> 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 | No<sup>2</sup> |
@ -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 = <path to folder>` parameter and a `scripts(<filename_1>, <filename_2>, ...)` 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 = <path to folder>` parameter and a `scripts(<filename_1>, <filename_2>, ...)` 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 order<sup>3</sup>:
@ -225,6 +224,6 @@ async fn test_create_comment(pool: PgPool) -> sqlx::Result<()> {
Multiple `fixtures` attributes can be used to combine different operating modes.
<sup>3</sup>Ordering 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.