objets_metier_rs 1.0.2

# CIAL Testing Guide


## Overview


This document describes the testing strategy for the CIAL (Gestion Commerciale) module of `objets_metier_rs`.

## Test Structure


### Integration Tests


Located in: `tests/integration_tests.rs`

These are **smoke tests** that verify all 34 CIAL factories are accessible and basic operations work.

#### Running Tests


```powershell
# Run all tests (most are marked #[ignore] and require Sage connection)

cargo test --test integration_tests -- --ignored

# Run only compilation tests (no Sage required)

cargo test --test integration_tests test_cial_types_compile
```

#### Environment Variables


Configure test database connection (all optional):

- `SAGE_USERNAME`: Sage username (default: `<Administrateur>`)
- `SAGE_PASSWORD`: Sage password (default: `""`)
- `SAGE_DATABASE`: Database path (default: `D:\TMP\BIJOU.MAE`)

Example:
```powershell
$env:SAGE_USERNAME = "<Administrateur>"
$env:SAGE_PASSWORD = ""
$env:SAGE_DATABASE = "D:\Sage\BIJOU.MAE"
cargo test --test integration_tests -- --ignored
```

#### Test Coverage


**Phase 1 - Core Factories (8)**:
- FactoryArticle
- FactoryFamille  
- FactoryDepot
- FactoryDocumentVente
- FactoryDocumentAchat
- FactoryDocumentStock
- FactoryDocumentInterne
- FactoryDocument

**Phase 2 - Configuration (5)**:
- FactoryGamme
- FactoryProduit
- FactoryUnite
- FactoryConditionnement
- FactoryGlossaire

**Phase 3 - Paramètres (16)**:
- 4 Catégories comptables (Vente, Achat, Stock, Tarif)
- 4 Paramètres documents (Vente, Achat, Stock, Interne)
- 4 Souches numérotation (Vente, Achat, Stock, Interne)
- 4 Autres (Modèle, ConditionLivraison, Expédition, Périodicité)

**Phase 4 - Avancées (5)**:
- FactoryBaremeCommission
- FactoryBaremeSolde
- FactoryBaremeRabais
- FactoryArticleStat
- FactoryArrondi (⚠️ special: no ExistIntitule)

### Test Cases


#### test_all_34_factories_accessible


Verifies all 34 factories can be obtained from `CialApplication`.

#### test_factory_article_list


Tests that `FactoryArticle.list()` returns results.

#### test_factory_arrondi_list


Tests `FactoryArrondi.list()` - special factory without ExistIntitule method.

#### test_cial_types_compile


Compilation-only test, no Sage connection needed. Ensures all factory types are properly exported.

## Examples


### Available Examples


1. **cial_complete_demo.rs** - Demonstrates all 34 factories
   - Tests accessibility of all phases
   - Shows basic operations (list, exist, read)
   - Organized by implementation phase

2. **cial_document_workflows.rs** - Document management
   - Sales, purchase, stock, internal documents
   - Document type analysis
   - Property access patterns

3. **cial_stock_management.rs** - Stock operations
   - Depot (warehouse) management
   - Stock document handling
   - Article stock information
   - Query operations

4. **cial_pricing_baremes.rs** - Pricing grids
   - Commission grids
   - Sales/promotion grids
   - Discount/rebate grids
   - Pricing categories
   - Rounding rules

### Running Examples


```powershell
# Set environment variables

$env:SAGE_USERNAME = "<Administrateur>"
$env:SAGE_PASSWORD = ""
$env:SAGE_DATABASE = "D:\Sage\BIJOU.MAE"

# Run specific example

cargo run --example cial_complete_demo
cargo run --example cial_document_workflows
cargo run --example cial_stock_management
cargo run --example cial_pricing_baremes
```

### Example Status


⚠️ **Note**: The new examples (cial_complete_demo, cial_document_workflows, etc.) demonstrate the intended API usage patterns but may need adjustments to match the actual factory API signatures. The existing `cial_demo.rs` example is known to work.

## Test Development Guidelines


### Writing New Tests


1. **Mark tests with #[ignore]** if they require Sage connection
2. **Use helper function** `connect_cial()` for consistent connection
3. **Test one factory at a time** for clear failure messages
4. **Handle errors gracefully** - database may not have test data

### Test Pattern


```rust
#[test]

#[ignore]

fn test_factory_example() -> SageResult<()> {
    let app = connect_cial()?;
    let factory = app.factory_example()?;
    
    // Test basic operation
    let items = factory.list()?;
    assert!(!items.is_empty_or_null(), "Should have items");
    
    // Test specific functionality
    // ...
    
    Ok(())
}
```

### API Notes


- Factories return `SafeVariant` for collections and objects
- Use `is_empty_or_null()` instead of `is_empty()` on SafeVariant
- Factory methods like `read_from()` may not take parameters (check implementation)
- `FactoryArrondi` is special - no `exist_intitule()` or `read_intitule()` methods

## Future Test Improvements


### Planned Additions


1. **Unit Tests** - Detailed tests for each factory
   - Property access tests
   - Create/Read/Update operations
   - Error handling
   - Query predicate tests

2. **Integration Workflows** - Complete business scenarios
   - Article creation with famille/gamme/unite
   - Document creation with lines
   - Stock movements between depots
   - Multi-document workflows

3. **Performance Tests** - Benchmarks
   - List operations on large datasets
   - Query performance
   - Caching effectiveness

4. **Mock Tests** - Tests without Sage dependency
   - COM interface mocking
   - API contract verification

## Continuous Integration


### GitHub Actions (Planned)


```yaml
# .github/workflows/test.yml

- name: Run compilation tests
  run: cargo test test_cial_types_compile

- name: Build examples
  run: cargo build --examples
```

### Local Development

```powershell
# Quick compilation check
cargo test test_cial_types_compile

# Full test with Sage (requires setup)
cargo test --test integration_tests -- --ignored

# Build all examples
cargo build --examples
```

## Troubleshooting


### Common Issues


**Error: Cannot connect to Sage**
- Verify Sage 100c is installed
- Check database path in `SAGE_DATABASE`
- Ensure user has permissions

**Error: Factory method signature mismatch**
- Check actual implementation in `src/wrappers/cial/factories/`
- Some methods may not take parameters as expected
- Refer to existing working examples

**Test hangs**
- May indicate COM deadlock
- Check for unclosed connections
- Ensure proper cleanup in tests

## References


- Main CIAL implementation: `src/wrappers/cial/`
- Factory implementations: `src/wrappers/cial/factories/`
- Existing working example: `examples/cial_demo.rs`
- TODO roadmap: `TODO.md` Phase 5 section