From a8ffd0007df0cd76910a961f710f215ea1b673a3 Mon Sep 17 00:00:00 2001 From: Jakob Date: Thu, 2 Apr 2026 12:00:00 +0200 Subject: [PATCH] Update README: add testing section, production build, test infrastructure docs --- README.md | 122 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 100 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 5580a15..f06f75d 100644 --- a/README.md +++ b/README.md @@ -12,32 +12,45 @@ This project processes petroleum/fuel station transaction data from CSV files an - **Invoice Generation**: Generate HTML invoices from CSV data (file-to-file mode) - **Multi-Environment**: Separate databases for development, testing, and production - **Sales Reporting**: Query transactions by customer, product, date range +- **Test-Driven Development**: Comprehensive test suite with 45 tests ## Project Structure ``` rusty-petroleum/ ├── Cargo.toml # Rust dependencies +├── Cargo.lock # Locked dependency versions ├── config.example.toml # Config template ├── migrations/ # SQL schema files -│ ├── 001_dev.sql -│ ├── 001_test.sql -│ ├── 001_prod.sql -│ └── 002_schema.sql +│ └── 002_schema.sql # Current schema ├── input/ # CSV input files ├── output/ # Generated invoices ├── src/ -│ ├── main.rs # CLI entry point -│ ├── config.rs # Configuration loading -│ ├── db/ # Database layer +│ ├── lib.rs # Library crate (for testing) +│ ├── main.rs # CLI entry point +│ ├── config.rs # Configuration loading +│ ├── db/ # Database layer +│ │ ├── mod.rs │ │ ├── connection.rs │ │ ├── models.rs │ │ └── repository.rs -│ ├── commands/ # CLI commands -│ │ ├── db.rs # db setup/reset -│ │ └── import.rs # CSV import +│ ├── commands/ # CLI commands +│ │ ├── mod.rs +│ │ ├── db.rs # db setup/reset +│ │ └── import.rs # CSV import │ └── invoice_generator.rs -└── templates/ # HTML invoice templates +├── templates/ # HTML invoice templates +│ ├── index.html +│ └── customer.html +└── tests/ # Integration tests + ├── common/ # Test utilities + │ ├── mod.rs + │ ├── fixtures.rs + │ └── test_db.rs + ├── config_test.rs # Config module tests + ├── import_test.rs # CSV parsing tests + ├── models_test.rs # Model tests + └── repository_test.rs # Database tests ``` ## Database Schema @@ -45,26 +58,30 @@ rusty-petroleum/ ### customers | Column | Type | Description | |--------|------|-------------| -| id | INT | Primary key | +| id | INT UNSIGNED | Primary key | | customer_number | VARCHAR | Unique customer identifier | -| card_report_group | TINYINT | Customer classification (1=fleet, 3/4=retail) | +| card_report_group | TINYINT UNSIGNED | Customer classification (1=fleet, 3/4=retail) | +| created_at | TIMESTAMP | Record creation time | +| updated_at | TIMESTAMP | Last update time | ### cards | Column | Type | Description | |--------|------|-------------| -| id | INT | Primary key | +| id | INT UNSIGNED | Primary key | | card_number | VARCHAR | Unique card identifier | -| customer_id | INT | FK to customers | +| customer_id | INT UNSIGNED | FK to customers | +| created_at | TIMESTAMP | Record creation time | +| updated_at | TIMESTAMP | Last update time | ### transactions | Column | Type | Description | |--------|------|-------------| -| id | BIGINT | Primary key | +| id | BIGINT UNSIGNED | Primary key | | transaction_date | DATETIME | Transaction timestamp | | batch_number | VARCHAR | Batch identifier | -| amount | DECIMAL | Transaction amount | -| volume | DECIMAL | Volume in liters | -| price | DECIMAL | Price per liter | +| amount | DECIMAL(10,2) | Transaction amount | +| volume | DECIMAL(10,3) | Volume in liters | +| price | DECIMAL(8,4) | Price per liter | | quality_code | INT | Product code | | quality_name | VARCHAR | Product name (95 Oktan, Diesel) | | card_number | VARCHAR | Card used (including anonymized) | @@ -73,14 +90,15 @@ rusty-petroleum/ | pump | VARCHAR | Pump number | | receipt | VARCHAR | Receipt number | | control_number | VARCHAR | Control/verification number | -| customer_id | INT | FK to customers (NULL for anonymized) | +| customer_id | INT UNSIGNED | FK to customers (NULL for anonymized) | +| created_at | TIMESTAMP | Record creation time | ## Configuration Copy the example config and edit with your database credentials: ```bash -cp config.example.toml config.dev.toml # or config.test.toml +cp config.example.toml config.dev.toml # or config.test.toml or config.prod.toml ``` Edit `config.dev.toml`: @@ -100,6 +118,12 @@ Config files are loaded in order: 2. `config..toml` (environment-specific, gitignored) 3. `config.example.toml` (fallback, tracked) +### Database Names by Environment + +- `rusty_petroleum_dev` - Development +- `rusty_petroleum_test` - Testing +- `rusty_petroleum_prod` - Production + ## Commands ```bash @@ -130,6 +154,53 @@ cargo run -- db reset --env dev cargo run -- generate input/409.csv output/ ``` +## Testing + +The project has a comprehensive test suite with 45 tests covering config, CSV parsing, models, and database operations. + +```bash +# Run all tests (lib + integration) +cargo test + +# Run only lib/unit tests (fast, no database needed) +cargo test --lib + +# Run only integration tests (requires test database) +cargo test --tests + +# Run a specific test file +cargo test --test config_test +cargo test --test import_test +cargo test --test repository_test + +# Run a specific test +cargo test customer_insert_returns_id + +# Run tests in release mode +cargo test --release +``` + +### Test Database Setup + +Repository tests require a test database. Run setup before testing: + +```bash +cargo run -- db setup --env test +``` + +## Production Build + +Build an optimized binary for production: + +```bash +# Build release binary +cargo build --release + +# Run the binary +./target/release/invoice-generator db setup --env prod +./target/release/invoice-generator import data.csv --env prod +``` + ## Current Status ### Implemented @@ -139,12 +210,12 @@ cargo run -- generate input/409.csv output/ - [x] Configuration via TOML files - [x] Invoice generation (HTML output) - [x] Database setup/reset commands +- [x] Unit tests (45 tests) ### TODO - [ ] Sales reporting queries (dashboard/API) - [ ] Customer invoice retrieval from database - [ ] Batch import across multiple CSV files -- [ ] Unit tests - [ ] CI/CD pipeline ## Technology Stack @@ -154,6 +225,7 @@ cargo run -- generate input/409.csv output/ - **ORM**: sqlx (async MySQL) - **Templating**: Askama (HTML templates) - **Config**: TOML +- **Testing**: tokio-test, tempfile ## Getting Started @@ -181,6 +253,12 @@ cargo run -- generate input/409.csv output/ cargo run -- import input/409.csv --env dev ``` +5. Run tests + ```bash + cargo test --lib # Unit tests (fast) + cargo test --tests # Integration tests (requires DB) + ``` + ## License See LICENSE file.