https://github.com/hgzimmerman/diesel_test_setup
Common utility for setting up databases for testing using Diesel
https://github.com/hgzimmerman/diesel_test_setup
Last synced: 2 months ago
JSON representation
Common utility for setting up databases for testing using Diesel
- Host: GitHub
- URL: https://github.com/hgzimmerman/diesel_test_setup
- Owner: hgzimmerman
- License: mit
- Created: 2019-05-21T00:33:59.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2020-01-27T22:02:38.000Z (over 5 years ago)
- Last Synced: 2025-02-28T09:11:07.448Z (3 months ago)
- Language: Rust
- Homepage:
- Size: 58.6 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Diesel Test Setup
[](https://travis-ci.org/hgzimmerman/diesel_test_setup)
A small library for setting up a database using Diesel, and then tearing down the database once the test is finished.
Given a connection to a database that has super user permissions, this library will create a new, uniquely-named database and run migrations on it.
Once a `Cleanup` struct that was created when the database was set up goes out of scope, its destructor will delete the database.
```rust
use diesel_test_setup::TestDatabaseBuilder;
{
let admin_conn = PgConnection::establish(ADMIN_DATABASE_URL).unwrap();
const DATABASE_ORIGIN: &str = "postgres://localhost";
let pool: EphemeralDatabasePool = TestDatabaseBuilder::new(
admin_conn,
DATABASE_ORIGIN
)
.setup_pool()
.expect("Could not create the database.");
let pool: &Pool> = pool.deref();
// Perform your test using the reference to a Pool
}
// Database has been cleaned up.
```
### Testing
The tests expect Postgres and MySql to be running and for specific environment variables to be set up before running.
Tests are intended to be ran using Docker with the following command `docker-compose run cargo test`.
### Features
* Creation of unique test databases and running of migrations.
* Automatic destruction of test databases.
* Supports PostgreSql and MySql.
* Both `r2d2::Pool`s and `diesel::Connection`s are supported.
### Wait!
Before you choose to use this library, there may be better options for your testing needs.
Take a look at Diesel's built-in [test_transaction](https://docs.diesel.rs/diesel/connection/trait.Connection.html#method.test_transaction).
Diesel Test Setup has higher overhead per-test because it needs to create, migrate, and delete a database for every test.
`test_transaction`, on the other hand, runs your code within a transaction and then rolls it back.
This library is well suited to running tests in an environment where there isn't significant initial test data, and you don't want to manually configure a separate test database than your development database.
It also is useful when you want to set up integration tests that rely on a server framework owning a `r2d2::Pool`.
While you can configure a `Pool` to begin a test transaction when a connection is given out, you then can't use multiple sequential queries using different connections in your tests.
Using `test_transaction` works great when you have an already populated test database, want to be able to run large queries against it without waiting for setup/data-population steps, and tests utilizing `Pool`s don't require state changes across multiple queries.
### Support Commitment
The scope and features of this project are pretty minimal and should be easy to maintain.
I consider this project to be feature-complete, although if you find something lacking, feel free to open an Issue or PR.
The crate is listed under `passively-maintained` in its `Cargo.toml`, should I cease to be able to maintain this crate,
I will alter that tag to `looking-for-maintainer`.