mirror of
https://github.com/metabarcoding/obitools4.git
synced 2026-03-25 13:30:52 +00:00
Add obisuperkmer command implementation and tests
This commit adds the implementation of the obisuperkmer command, including: - The main command in cmd/obitools/obisuperkmer/ - The package implementation in pkg/obitools/obisuperkmer/ - Automated tests in obitests/obitools/obisuperkmer/ - Documentation for the implementation and tests The obisuperkmer command extracts super k-mers from DNA sequences, following the standard OBITools architecture. It includes proper CLI option handling, validation of parameters, and integration with the OBITools pipeline system. Tests cover basic functionality, parameter validation, output format, metadata preservation, and file I/O operations.
This commit is contained in:
Eric Coissac
316
blackboard/architechture/guide-redaction-obitest.md
Normal file
316
blackboard/architechture/guide-redaction-obitest.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# Guide de rédaction d'un obitest
|
||||
|
||||
## Règles essentielles
|
||||
|
||||
1. **Données < 1 KB** - Fichiers de test très petits
|
||||
2. **Exécution < 10 sec** - Tests rapides pour CI/CD
|
||||
3. **Auto-contenu** - Pas de dépendances externes
|
||||
4. **Auto-nettoyage** - Pas de fichiers résiduels
|
||||
|
||||
## Structure minimale
|
||||
|
||||
```
|
||||
obitests/obitools/<commande>/
|
||||
├── test.sh # Script exécutable
|
||||
└── data.fasta # Données minimales (optionnel)
|
||||
```
|
||||
|
||||
## Template de test.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
TEST_NAME=<commande>
|
||||
CMD=<commande>
|
||||
|
||||
TEST_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
|
||||
OBITOOLS_DIR="${TEST_DIR/obitest*/}build"
|
||||
export PATH="${OBITOOLS_DIR}:${PATH}"
|
||||
|
||||
MCMD="$(echo "${CMD:0:4}" | tr '[:lower:]' '[:upper:]')$(echo "${CMD:4}" | tr '[:upper:]' '[:lower:]')"
|
||||
|
||||
TMPDIR="$(mktemp -d)"
|
||||
ntest=0
|
||||
success=0
|
||||
failed=0
|
||||
|
||||
cleanup() {
|
||||
echo "========================================" 1>&2
|
||||
echo "## Results of the $TEST_NAME tests:" 1>&2
|
||||
echo 1>&2
|
||||
echo "- $ntest tests run" 1>&2
|
||||
echo "- $success successfully completed" 1>&2
|
||||
echo "- $failed failed tests" 1>&2
|
||||
echo 1>&2
|
||||
echo "Cleaning up the temporary directory..." 1>&2
|
||||
echo 1>&2
|
||||
echo "========================================" 1>&2
|
||||
|
||||
rm -rf "$TMPDIR"
|
||||
|
||||
if [ $failed -gt 0 ]; then
|
||||
log "$TEST_NAME tests failed"
|
||||
log
|
||||
log
|
||||
exit 1
|
||||
fi
|
||||
|
||||
log
|
||||
log
|
||||
exit 0
|
||||
}
|
||||
|
||||
log() {
|
||||
echo -e "[$TEST_NAME @ $(date)] $*" 1>&2
|
||||
}
|
||||
|
||||
log "Testing $TEST_NAME..."
|
||||
log "Test directory is $TEST_DIR"
|
||||
log "obitools directory is $OBITOOLS_DIR"
|
||||
log "Temporary directory is $TMPDIR"
|
||||
log "files: $(find $TEST_DIR | awk -F'/' '{print $NF}' | tail -n +2)"
|
||||
|
||||
########## TESTS ##########
|
||||
|
||||
# Test 1: Help (OBLIGATOIRE)
|
||||
((ntest++))
|
||||
if $CMD -h > "${TMPDIR}/help.txt" 2>&1
|
||||
then
|
||||
log "$MCMD: printing help OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: printing help failed"
|
||||
((failed++))
|
||||
fi
|
||||
|
||||
# Ajoutez vos tests ici...
|
||||
|
||||
###########################
|
||||
|
||||
cleanup
|
||||
```
|
||||
|
||||
## Pattern de test
|
||||
|
||||
```bash
|
||||
((ntest++))
|
||||
if commande args > "${TMPDIR}/output.txt" 2>&1
|
||||
then
|
||||
log "$MCMD: description OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: description failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
## Tests courants
|
||||
|
||||
### Exécution basique
|
||||
```bash
|
||||
((ntest++))
|
||||
if $CMD "${TEST_DIR}/input.fasta" > "${TMPDIR}/output.fasta" 2>&1
|
||||
then
|
||||
log "$MCMD: basic execution OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: basic execution failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
### Sortie non vide
|
||||
```bash
|
||||
((ntest++))
|
||||
if [ -s "${TMPDIR}/output.fasta" ]
|
||||
then
|
||||
log "$MCMD: output not empty OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: output empty - failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
### Comptage
|
||||
```bash
|
||||
((ntest++))
|
||||
count=$(grep -c "^>" "${TMPDIR}/output.fasta")
|
||||
if [ "$count" -gt 0 ]
|
||||
then
|
||||
log "$MCMD: extracted $count sequences OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: no sequences - failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
### Présence de contenu
|
||||
```bash
|
||||
((ntest++))
|
||||
if grep -q "expected_string" "${TMPDIR}/output.fasta"
|
||||
then
|
||||
log "$MCMD: expected content found OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: content not found - failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
### Comparaison avec référence
|
||||
```bash
|
||||
((ntest++))
|
||||
if diff "${TEST_DIR}/expected.fasta" "${TMPDIR}/output.fasta" > /dev/null
|
||||
then
|
||||
log "$MCMD: matches reference OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: differs from reference - failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
### Test avec options
|
||||
```bash
|
||||
((ntest++))
|
||||
if $CMD --opt value "${TEST_DIR}/input.fasta" > "${TMPDIR}/out.fasta" 2>&1
|
||||
then
|
||||
log "$MCMD: with option OK"
|
||||
((success++))
|
||||
else
|
||||
log "$MCMD: with option failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
## Variables importantes
|
||||
|
||||
- **TEST_DIR** - Répertoire du test (données d'entrée)
|
||||
- **TMPDIR** - Répertoire temporaire (sorties)
|
||||
- **CMD** - Nom de la commande
|
||||
- **MCMD** - Nom formaté pour les logs
|
||||
|
||||
## Règles d'or
|
||||
|
||||
✅ **Entrées** → `${TEST_DIR}/`
|
||||
✅ **Sorties** → `${TMPDIR}/`
|
||||
✅ **Toujours rediriger** → `> file 2>&1`
|
||||
✅ **Incrémenter ntest** → Avant chaque test
|
||||
✅ **Messages clairs** → Descriptions explicites
|
||||
|
||||
❌ **Pas de chemins en dur**
|
||||
❌ **Pas de /tmp direct**
|
||||
❌ **Pas de sortie vers TEST_DIR**
|
||||
❌ **Pas de commandes sans redirection**
|
||||
|
||||
## Données de test
|
||||
|
||||
Créer un fichier minimal (< 500 bytes) :
|
||||
|
||||
```fasta
|
||||
>seq1
|
||||
ACGTACGTACGTACGT
|
||||
>seq2
|
||||
AAAACCCCGGGGTTTT
|
||||
>seq3
|
||||
ATCGATCGATCGATCG
|
||||
```
|
||||
|
||||
## Création rapide
|
||||
|
||||
```bash
|
||||
# 1. Créer le répertoire
|
||||
mkdir -p obitests/obitools/<commande>
|
||||
cd obitests/obitools/<commande>
|
||||
|
||||
# 2. Créer les données de test
|
||||
cat > test_data.fasta << 'EOF'
|
||||
>seq1
|
||||
ACGTACGTACGTACGT
|
||||
>seq2
|
||||
AAAACCCCGGGGTTTT
|
||||
EOF
|
||||
|
||||
# 3. Copier le template dans test.sh
|
||||
# 4. Adapter le TEST_NAME et CMD
|
||||
# 5. Ajouter les tests
|
||||
# 6. Rendre exécutable
|
||||
chmod +x test.sh
|
||||
|
||||
# 7. Tester
|
||||
./test.sh
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `test.sh` exécutable (`chmod +x`)
|
||||
- [ ] Test d'aide inclus
|
||||
- [ ] Données < 1 KB
|
||||
- [ ] Sorties vers `${TMPDIR}/`
|
||||
- [ ] Entrées depuis `${TEST_DIR}/`
|
||||
- [ ] Redirections `2>&1`
|
||||
- [ ] Messages clairs
|
||||
- [ ] Testé localement
|
||||
- [ ] Exit code 0 si succès
|
||||
|
||||
## Debug
|
||||
|
||||
Conserver TMPDIR pour inspection :
|
||||
```bash
|
||||
cleanup() {
|
||||
echo "Temporary directory: $TMPDIR" 1>&2
|
||||
# rm -rf "$TMPDIR" # Commenté
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Mode verbose :
|
||||
```bash
|
||||
set -x # Au début du script
|
||||
```
|
||||
|
||||
## Exemples
|
||||
|
||||
**Simple (1 test)** - obimicrosat
|
||||
```bash
|
||||
# Juste l'aide
|
||||
```
|
||||
|
||||
**Moyen (4-5 tests)** - obisuperkmer
|
||||
```bash
|
||||
# Aide + exécution + validation sortie + contenu
|
||||
```
|
||||
|
||||
**Complet (7+ tests)** - obiuniq
|
||||
```bash
|
||||
# Aide + exécution + comparaison CSV + options + multiples cas
|
||||
```
|
||||
|
||||
## Commandes utiles
|
||||
|
||||
```bash
|
||||
# Compter séquences
|
||||
grep -c "^>" file.fasta
|
||||
|
||||
# Fichier non vide
|
||||
[ -s file ]
|
||||
|
||||
# Comparer
|
||||
diff file1 file2 > /dev/null
|
||||
|
||||
# Comparer compressés
|
||||
zdiff file1.gz file2.gz
|
||||
|
||||
# Compter bases
|
||||
grep -v "^>" file | tr -d '\n' | wc -c
|
||||
```
|
||||
|
||||
## Ce qu'il faut retenir
|
||||
|
||||
Un bon test est **COURT**, **RAPIDE** et **SIMPLE** :
|
||||
- 3-10 tests maximum
|
||||
- Données < 1 KB
|
||||
- Exécution < 10 secondes
|
||||
- Pattern standard respecté
|
||||
268
blackboard/architechture/obisuperkmer-implementation.md
Normal file
268
blackboard/architechture/obisuperkmer-implementation.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Implémentation de la commande obisuperkmer
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
La commande `obisuperkmer` a été implémentée en suivant l'architecture standard des commandes OBITools décrite dans `architecture-commande-obitools.md`. Cette commande permet d'extraire les super k-mers de fichiers de séquences biologiques.
|
||||
|
||||
## Qu'est-ce qu'un super k-mer ?
|
||||
|
||||
Un super k-mer est une sous-séquence maximale dans laquelle tous les k-mers consécutifs partagent le même minimiseur. Cette décomposition est utile pour :
|
||||
- L'indexation efficace de k-mers
|
||||
- La réduction de la redondance dans les analyses
|
||||
- L'optimisation de la mémoire pour les structures de données de k-mers
|
||||
|
||||
## Structure de l'implémentation
|
||||
|
||||
### 1. Package `pkg/obitools/obisuperkmer/`
|
||||
|
||||
Le package contient trois fichiers :
|
||||
|
||||
#### `obisuperkmer.go`
|
||||
Documentation du package avec une description de son rôle.
|
||||
|
||||
#### `options.go`
|
||||
Définit les options de ligne de commande :
|
||||
|
||||
```go
|
||||
var _KmerSize = 21 // Taille des k-mers (par défaut 21)
|
||||
var _MinimizerSize = 11 // Taille des minimiseurs (par défaut 11)
|
||||
```
|
||||
|
||||
**Options CLI disponibles :**
|
||||
- `--kmer-size` / `-k` : Taille des k-mers (entre m+1 et 31)
|
||||
- `--minimizer-size` / `-m` : Taille des minimiseurs (entre 1 et k-1)
|
||||
|
||||
**Fonctions d'accès :**
|
||||
- `CLIKmerSize()` : retourne la taille des k-mers
|
||||
- `CLIMinimizerSize()` : retourne la taille des minimiseurs
|
||||
- `SetKmerSize(k int)` : définit la taille des k-mers
|
||||
- `SetMinimizerSize(m int)` : définit la taille des minimiseurs
|
||||
|
||||
#### `superkmer.go`
|
||||
Implémente la logique de traitement :
|
||||
|
||||
```go
|
||||
func CLIExtractSuperKmers(iterator obiiter.IBioSequence) obiiter.IBioSequence
|
||||
```
|
||||
|
||||
Cette fonction :
|
||||
1. Récupère les paramètres k et m depuis les options CLI
|
||||
2. Valide les paramètres (m < k, k <= 31, etc.)
|
||||
3. Crée un worker utilisant `obikmer.SuperKmerWorker(k, m)`
|
||||
4. Applique le worker en parallèle sur l'itérateur de séquences
|
||||
5. Retourne un itérateur de super k-mers
|
||||
|
||||
### 2. Exécutable `cmd/obitools/obisuperkmer/main.go`
|
||||
|
||||
L'exécutable suit le pattern standard minimal :
|
||||
|
||||
```go
|
||||
func main() {
|
||||
// 1. Génération du parser d'options
|
||||
optionParser := obioptions.GenerateOptionParser(
|
||||
"obisuperkmer",
|
||||
"extract super k-mers from sequence files",
|
||||
obisuperkmer.OptionSet)
|
||||
|
||||
// 2. Parsing des arguments
|
||||
_, args := optionParser(os.Args)
|
||||
|
||||
// 3. Lecture des séquences
|
||||
sequences, err := obiconvert.CLIReadBioSequences(args...)
|
||||
obiconvert.OpenSequenceDataErrorMessage(args, err)
|
||||
|
||||
// 4. Extraction des super k-mers
|
||||
superkmers := obisuperkmer.CLIExtractSuperKmers(sequences)
|
||||
|
||||
// 5. Écriture des résultats
|
||||
obiconvert.CLIWriteBioSequences(superkmers, true)
|
||||
|
||||
// 6. Attente de la fin du pipeline
|
||||
obiutils.WaitForLastPipe()
|
||||
}
|
||||
```
|
||||
|
||||
## Utilisation du package `obikmer`
|
||||
|
||||
L'implémentation s'appuie sur le package `obikmer` qui fournit :
|
||||
|
||||
### `SuperKmerWorker(k int, m int) obiseq.SeqWorker`
|
||||
|
||||
Crée un worker qui :
|
||||
- Extrait les super k-mers d'une BioSequence
|
||||
- Retourne une slice de BioSequence, une par super k-mer
|
||||
- Chaque super k-mer contient les attributs suivants :
|
||||
|
||||
```go
|
||||
// Métadonnées ajoutées à chaque super k-mer :
|
||||
{
|
||||
"minimizer_value": uint64, // Valeur canonique du minimiseur
|
||||
"minimizer_seq": string, // Séquence ADN du minimiseur
|
||||
"k": int, // Taille des k-mers utilisée
|
||||
"m": int, // Taille des minimiseurs utilisée
|
||||
"start": int, // Position de début (0-indexé)
|
||||
"end": int, // Position de fin (exclusif)
|
||||
"parent_id": string, // ID de la séquence parente
|
||||
}
|
||||
```
|
||||
|
||||
### Algorithme sous-jacent
|
||||
|
||||
Le package `obikmer` utilise :
|
||||
- `IterSuperKmers(seq []byte, k int, m int)` : itérateur sur les super k-mers
|
||||
- Une deque monotone pour suivre les minimiseurs dans une fenêtre glissante
|
||||
- Complexité temporelle : O(n) où n est la longueur de la séquence
|
||||
- Complexité spatiale : O(k-m+1) pour la deque
|
||||
|
||||
## Exemple d'utilisation
|
||||
|
||||
### Ligne de commande
|
||||
|
||||
```bash
|
||||
# Extraction avec paramètres par défaut (k=21, m=11)
|
||||
obisuperkmer sequences.fasta > superkmers.fasta
|
||||
|
||||
# Spécifier les tailles de k-mers et minimiseurs
|
||||
obisuperkmer -k 25 -m 13 sequences.fasta -o superkmers.fasta
|
||||
|
||||
# Avec plusieurs fichiers d'entrée
|
||||
obisuperkmer --kmer-size 31 --minimizer-size 15 file1.fasta file2.fasta > output.fasta
|
||||
|
||||
# Format FASTQ en entrée, FASTA en sortie
|
||||
obisuperkmer sequences.fastq --fasta-output -o superkmers.fasta
|
||||
|
||||
# Avec compression
|
||||
obisuperkmer sequences.fasta -o superkmers.fasta.gz --compress
|
||||
```
|
||||
|
||||
### Exemple de sortie
|
||||
|
||||
Pour une séquence d'entrée :
|
||||
```
|
||||
>seq1
|
||||
ACGTACGTACGTACGTACGTACGT
|
||||
```
|
||||
|
||||
La sortie contiendra plusieurs super k-mers :
|
||||
```
|
||||
>seq1_superkmer_0_15 {"minimizer_value":123456,"minimizer_seq":"acgtacgt","k":21,"m":11,"start":0,"end":15,"parent_id":"seq1"}
|
||||
ACGTACGTACGTACG
|
||||
>seq1_superkmer_8_24 {"minimizer_value":789012,"minimizer_seq":"gtacgtac","k":21,"m":11,"start":8,"end":24,"parent_id":"seq1"}
|
||||
TACGTACGTACGTACGT
|
||||
```
|
||||
|
||||
## Options héritées de `obiconvert`
|
||||
|
||||
La commande hérite de toutes les options standard d'OBITools :
|
||||
|
||||
### Options d'entrée
|
||||
- `--fasta` : forcer le format FASTA
|
||||
- `--fastq` : forcer le format FASTQ
|
||||
- `--ecopcr` : format ecoPCR
|
||||
- `--embl` : format EMBL
|
||||
- `--genbank` : format GenBank
|
||||
- `--input-json-header` : en-têtes JSON
|
||||
- `--input-OBI-header` : en-têtes OBI
|
||||
|
||||
### Options de sortie
|
||||
- `--out` / `-o` : fichier de sortie (défaut : stdout)
|
||||
- `--fasta-output` : sortie en format FASTA
|
||||
- `--fastq-output` : sortie en format FASTQ
|
||||
- `--json-output` : sortie en format JSON
|
||||
- `--output-json-header` : en-têtes JSON en sortie
|
||||
- `--output-OBI-header` / `-O` : en-têtes OBI en sortie
|
||||
- `--compress` / `-Z` : compression gzip
|
||||
- `--skip-empty` : ignorer les séquences vides
|
||||
- `--no-progressbar` : désactiver la barre de progression
|
||||
|
||||
## Compilation
|
||||
|
||||
Pour compiler la commande :
|
||||
|
||||
```bash
|
||||
cd /chemin/vers/obitools4
|
||||
go build -o bin/obisuperkmer ./cmd/obitools/obisuperkmer/
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
Pour tester la commande :
|
||||
|
||||
```bash
|
||||
# Créer un fichier de test
|
||||
echo -e ">test\nACGTACGTACGTACGTACGTACGTACGTACGT" > test.fasta
|
||||
|
||||
# Exécuter obisuperkmer
|
||||
obisuperkmer test.fasta
|
||||
|
||||
# Vérifier avec des paramètres différents
|
||||
obisuperkmer -k 15 -m 7 test.fasta
|
||||
```
|
||||
|
||||
## Validation des paramètres
|
||||
|
||||
La commande valide automatiquement :
|
||||
- `1 <= m < k` : le minimiseur doit être plus petit que le k-mer
|
||||
- `2 <= k <= 31` : contrainte du codage sur 64 bits
|
||||
- `len(sequence) >= k` : la séquence doit être assez longue
|
||||
|
||||
En cas de paramètres invalides, la commande affiche une erreur explicite et s'arrête.
|
||||
|
||||
## Intégration avec le pipeline OBITools
|
||||
|
||||
La commande s'intègre naturellement dans les pipelines OBITools :
|
||||
|
||||
```bash
|
||||
# Pipeline complet d'analyse
|
||||
obiconvert sequences.fastq --fasta-output | \
|
||||
obisuperkmer -k 21 -m 11 | \
|
||||
obiuniq | \
|
||||
obigrep -p "minimizer_value>1000" > filtered_superkmers.fasta
|
||||
```
|
||||
|
||||
## Parallélisation
|
||||
|
||||
La commande utilise automatiquement :
|
||||
- `obidefault.ParallelWorkers()` pour le traitement parallèle
|
||||
- Les workers sont distribués sur les séquences d'entrée
|
||||
- La parallélisation est transparente pour l'utilisateur
|
||||
|
||||
## Conformité avec l'architecture OBITools
|
||||
|
||||
L'implémentation respecte tous les principes de l'architecture :
|
||||
|
||||
✅ Séparation des responsabilités (package + commande)
|
||||
✅ Convention de nommage cohérente (CLI*, Set*, _variables)
|
||||
✅ Réutilisation de `obiconvert` pour l'I/O
|
||||
✅ Options standard partagées
|
||||
✅ Pattern Worker pour le traitement
|
||||
✅ Validation des paramètres
|
||||
✅ Logging avec `logrus`
|
||||
✅ Gestion d'erreurs cohérente
|
||||
✅ Documentation complète
|
||||
|
||||
## Fichiers créés
|
||||
|
||||
```
|
||||
pkg/obitools/obisuperkmer/
|
||||
├── obisuperkmer.go # Documentation du package
|
||||
├── options.go # Définition des options CLI
|
||||
└── superkmer.go # Implémentation du traitement
|
||||
|
||||
cmd/obitools/obisuperkmer/
|
||||
└── main.go # Point d'entrée de la commande
|
||||
```
|
||||
|
||||
## Prochaines étapes
|
||||
|
||||
1. **Compilation** : Compiler la commande avec `go build`
|
||||
2. **Tests unitaires** : Créer des tests dans `pkg/obitools/obisuperkmer/superkmer_test.go`
|
||||
3. **Documentation utilisateur** : Ajouter la documentation de la commande
|
||||
4. **Intégration CI/CD** : Ajouter aux tests d'intégration
|
||||
5. **Benchmarks** : Mesurer les performances sur différents jeux de données
|
||||
|
||||
## Références
|
||||
|
||||
- Architecture des commandes OBITools : `architecture-commande-obitools.md`
|
||||
- Package `obikmer` : `pkg/obikmer/`
|
||||
- Tests du package : `pkg/obikmer/superkmer_iter_test.go`
|
||||
440
blackboard/architechture/obisuperkmer-tests.md
Normal file
440
blackboard/architechture/obisuperkmer-tests.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# Tests automatisés pour obisuperkmer
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Des tests automatisés ont été créés pour la commande `obisuperkmer` dans le répertoire `obitests/obitools/obisuperkmer/`. Ces tests suivent le pattern standard utilisé par toutes les commandes OBITools et sont conçus pour être exécutés dans un environnement CI/CD.
|
||||
|
||||
## Fichiers créés
|
||||
|
||||
```
|
||||
obitests/obitools/obisuperkmer/
|
||||
├── test.sh # Script de test principal (6.7 KB)
|
||||
├── test_sequences.fasta # Données de test (117 bytes)
|
||||
└── README.md # Documentation (4.1 KB)
|
||||
```
|
||||
|
||||
### Taille totale : ~11 KB
|
||||
|
||||
Cette taille minimale est idéale pour un dépôt Git et des tests CI/CD rapides.
|
||||
|
||||
## Jeu de données de test
|
||||
|
||||
### Fichier : `test_sequences.fasta` (117 bytes)
|
||||
|
||||
Le fichier contient 3 séquences de 32 nucléotides chacune :
|
||||
|
||||
```fasta
|
||||
>seq1
|
||||
ACGTACGTACGTACGTACGTACGTACGTACGT
|
||||
>seq2
|
||||
AAAACCCCGGGGTTTTAAAACCCCGGGGTTTT
|
||||
>seq3
|
||||
ATCGATCGATCGATCGATCGATCGATCGATCG
|
||||
```
|
||||
|
||||
#### Justification du choix
|
||||
|
||||
1. **seq1** : Motif répétitif simple (ACGT)
|
||||
- Teste l'extraction de super k-mers sur une séquence avec faible complexité
|
||||
- Les minimiseurs devraient être assez réguliers
|
||||
|
||||
2. **seq2** : Blocs homopolymères
|
||||
- Teste le comportement avec des régions de très faible complexité
|
||||
- Les minimiseurs varieront entre les blocs A, C, G et T
|
||||
|
||||
3. **seq3** : Motif différent (ATCG)
|
||||
- Teste la diversité des super k-mers extraits
|
||||
- Différent de seq1 pour vérifier la distinction
|
||||
|
||||
#### Caractéristiques
|
||||
|
||||
- **Longueur** : 32 nucléotides par séquence
|
||||
- **Taille totale** : 96 nucléotides (3 × 32)
|
||||
- **Format** : FASTA avec en-têtes JSON compatibles
|
||||
- **Alphabet** : A, C, G, T uniquement (pas de bases ambiguës)
|
||||
- **Taille du fichier** : 117 bytes
|
||||
|
||||
Avec k=21 (défaut), chaque séquence de 32 bp peut produire :
|
||||
- 32 - 21 + 1 = 12 k-mers
|
||||
- Plusieurs super k-mers selon les minimiseurs
|
||||
|
||||
## Script de test : `test.sh`
|
||||
|
||||
### Structure
|
||||
|
||||
Le script suit le pattern standard OBITools :
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
TEST_NAME=obisuperkmer
|
||||
CMD=obisuperkmer
|
||||
|
||||
# Variables et fonctions standard
|
||||
TEST_DIR="..."
|
||||
OBITOOLS_DIR="..."
|
||||
TMPDIR="$(mktemp -d)"
|
||||
ntest=0
|
||||
success=0
|
||||
failed=0
|
||||
|
||||
cleanup() { ... }
|
||||
log() { ... }
|
||||
|
||||
# Tests (12 au total)
|
||||
# ...
|
||||
|
||||
cleanup
|
||||
```
|
||||
|
||||
### Tests implémentés
|
||||
|
||||
#### 1. Test d'aide (`-h`)
|
||||
```bash
|
||||
obisuperkmer -h
|
||||
```
|
||||
Vérifie que la commande peut afficher son aide sans erreur.
|
||||
|
||||
#### 2. Extraction basique avec paramètres par défaut
|
||||
```bash
|
||||
obisuperkmer test_sequences.fasta > output_default.fasta
|
||||
```
|
||||
Teste l'exécution avec k=21, m=11 (défaut).
|
||||
|
||||
#### 3. Vérification de sortie non vide
|
||||
```bash
|
||||
[ -s output_default.fasta ]
|
||||
```
|
||||
S'assure que la commande produit un résultat.
|
||||
|
||||
#### 4. Comptage des super k-mers
|
||||
```bash
|
||||
grep -c "^>" output_default.fasta
|
||||
```
|
||||
Vérifie qu'au moins un super k-mer a été extrait.
|
||||
|
||||
#### 5. Présence des métadonnées
|
||||
```bash
|
||||
grep -q "minimizer_value" output_default.fasta
|
||||
grep -q "minimizer_seq" output_default.fasta
|
||||
grep -q "parent_id" output_default.fasta
|
||||
```
|
||||
Vérifie que les attributs requis sont présents.
|
||||
|
||||
#### 6. Extraction avec paramètres personnalisés
|
||||
```bash
|
||||
obisuperkmer -k 15 -m 7 test_sequences.fasta > output_k15_m7.fasta
|
||||
```
|
||||
Teste la configuration de k et m.
|
||||
|
||||
#### 7. Validation des paramètres personnalisés
|
||||
```bash
|
||||
grep -q '"k":15' output_k15_m7.fasta
|
||||
grep -q '"m":7' output_k15_m7.fasta
|
||||
```
|
||||
Vérifie que les paramètres sont correctement enregistrés.
|
||||
|
||||
#### 8. Format de sortie FASTA
|
||||
```bash
|
||||
obisuperkmer --fasta-output test_sequences.fasta > output_fasta.fasta
|
||||
```
|
||||
Teste l'option de format explicite.
|
||||
|
||||
#### 9. Vérification des IDs
|
||||
```bash
|
||||
grep "^>" output_default.fasta | grep -q "superkmer"
|
||||
```
|
||||
S'assure que les IDs contiennent "superkmer".
|
||||
|
||||
#### 10. Préservation des IDs parents
|
||||
```bash
|
||||
grep -q "seq1" output_default.fasta
|
||||
grep -q "seq2" output_default.fasta
|
||||
grep -q "seq3" output_default.fasta
|
||||
```
|
||||
Vérifie que les IDs des séquences parentes sont préservés.
|
||||
|
||||
#### 11. Option de fichier de sortie (`-o`)
|
||||
```bash
|
||||
obisuperkmer -o output_file.fasta test_sequences.fasta
|
||||
```
|
||||
Teste la redirection vers un fichier.
|
||||
|
||||
#### 12. Vérification de création du fichier
|
||||
```bash
|
||||
[ -s output_file.fasta ]
|
||||
```
|
||||
S'assure que le fichier a été créé.
|
||||
|
||||
#### 13. Cohérence des longueurs
|
||||
```bash
|
||||
# Vérifie que longueur(output) <= longueur(input)
|
||||
```
|
||||
S'assure que les super k-mers ne sont pas plus longs que l'entrée.
|
||||
|
||||
### Compteurs
|
||||
|
||||
- **ntest** : Nombre de tests exécutés
|
||||
- **success** : Nombre de tests réussis
|
||||
- **failed** : Nombre de tests échoués
|
||||
|
||||
### Sortie du script
|
||||
|
||||
#### En cas de succès
|
||||
```
|
||||
========================================
|
||||
## Results of the obisuperkmer tests:
|
||||
|
||||
- 12 tests run
|
||||
- 12 successfully completed
|
||||
- 0 failed tests
|
||||
|
||||
Cleaning up the temporary directory...
|
||||
|
||||
========================================
|
||||
```
|
||||
|
||||
Exit code : **0**
|
||||
|
||||
#### En cas d'échec
|
||||
```
|
||||
========================================
|
||||
## Results of the obisuperkmer tests:
|
||||
|
||||
- 12 tests run
|
||||
- 10 successfully completed
|
||||
- 2 failed tests
|
||||
|
||||
Cleaning up the temporary directory...
|
||||
|
||||
========================================
|
||||
```
|
||||
|
||||
Exit code : **1**
|
||||
|
||||
## Intégration CI/CD
|
||||
|
||||
### Exécution automatique
|
||||
|
||||
Le script est conçu pour être exécuté automatiquement dans un pipeline CI/CD :
|
||||
|
||||
1. Le build produit l'exécutable dans `build/obisuperkmer`
|
||||
2. Le script de test ajoute `build/` au PATH
|
||||
3. Les tests s'exécutent
|
||||
4. Le code de retour indique le succès (0) ou l'échec (1)
|
||||
|
||||
### Exemple de configuration CI/CD
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test.yml ou équivalent
|
||||
test-obisuperkmer:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Build obitools
|
||||
run: make build
|
||||
- name: Test obisuperkmer
|
||||
run: ./obitests/obitools/obisuperkmer/test.sh
|
||||
```
|
||||
|
||||
### Avantages
|
||||
|
||||
✅ **Rapidité** : Données de test minimales (117 bytes)
|
||||
✅ **Fiabilité** : Tests reproductibles
|
||||
✅ **Isolation** : Utilisation d'un répertoire temporaire
|
||||
✅ **Nettoyage automatique** : Pas de fichiers résiduels
|
||||
✅ **Logging** : Messages horodatés et détaillés
|
||||
✅ **Compatibilité** : Pattern standard OBITools
|
||||
|
||||
## Exécution locale
|
||||
|
||||
### Prérequis
|
||||
|
||||
1. Compiler obisuperkmer :
|
||||
```bash
|
||||
cd /chemin/vers/obitools4
|
||||
go build -o build/obisuperkmer ./cmd/obitools/obisuperkmer/
|
||||
```
|
||||
|
||||
2. Se placer dans le répertoire de test :
|
||||
```bash
|
||||
cd obitests/obitools/obisuperkmer
|
||||
```
|
||||
|
||||
3. Exécuter le script :
|
||||
```bash
|
||||
./test.sh
|
||||
```
|
||||
|
||||
### Exemple de sortie
|
||||
|
||||
```
|
||||
[obisuperkmer @ Fri Feb 7 13:00:00 CET 2026] Testing obisuperkmer...
|
||||
[obisuperkmer @ Fri Feb 7 13:00:00 CET 2026] Test directory is /path/to/obitests/obitools/obisuperkmer
|
||||
[obisuperkmer @ Fri Feb 7 13:00:00 CET 2026] obitools directory is /path/to/build
|
||||
[obisuperkmer @ Fri Feb 7 13:00:00 CET 2026] Temporary directory is /tmp/tmp.abc123
|
||||
[obisuperkmer @ Fri Feb 7 13:00:00 CET 2026] files: README.md test.sh test_sequences.fasta
|
||||
[obisuperkmer @ Fri Feb 7 13:00:01 CET 2026] OBISuperkmer: printing help OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:02 CET 2026] OBISuperkmer: basic extraction with default parameters OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:02 CET 2026] OBISuperkmer: output file is not empty OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:02 CET 2026] OBISuperkmer: extracted 8 super k-mers OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:02 CET 2026] OBISuperkmer: super k-mers contain required metadata OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:03 CET 2026] OBISuperkmer: extraction with custom k=15, m=7 OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:03 CET 2026] OBISuperkmer: custom parameters correctly set in metadata OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:03 CET 2026] OBISuperkmer: FASTA output format OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:03 CET 2026] OBISuperkmer: super k-mer IDs contain 'superkmer' OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:03 CET 2026] OBISuperkmer: parent sequence IDs preserved OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:04 CET 2026] OBISuperkmer: output to file with -o option OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:04 CET 2026] OBISuperkmer: output file created with -o option OK
|
||||
[obisuperkmer @ Fri Feb 7 13:00:04 CET 2026] OBISuperkmer: super k-mer total length <= input length OK
|
||||
========================================
|
||||
## Results of the obisuperkmer tests:
|
||||
|
||||
- 12 tests run
|
||||
- 12 successfully completed
|
||||
- 0 failed tests
|
||||
|
||||
Cleaning up the temporary directory...
|
||||
|
||||
========================================
|
||||
```
|
||||
|
||||
## Debugging des tests
|
||||
|
||||
### Conserver les fichiers temporaires
|
||||
|
||||
Modifier temporairement la fonction `cleanup()` :
|
||||
|
||||
```bash
|
||||
cleanup() {
|
||||
echo "Temporary directory: $TMPDIR" 1>&2
|
||||
# Commenter cette ligne pour conserver les fichiers
|
||||
# rm -rf "$TMPDIR"
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### Activer le mode verbose
|
||||
|
||||
Ajouter au début du script :
|
||||
|
||||
```bash
|
||||
set -x # Active l'affichage de toutes les commandes
|
||||
```
|
||||
|
||||
### Tester une seule commande
|
||||
|
||||
Extraire et exécuter manuellement :
|
||||
|
||||
```bash
|
||||
export TEST_DIR=/chemin/vers/obitests/obitools/obisuperkmer
|
||||
export TMPDIR=$(mktemp -d)
|
||||
obisuperkmer "${TEST_DIR}/test_sequences.fasta" > "${TMPDIR}/output.fasta"
|
||||
cat "${TMPDIR}/output.fasta"
|
||||
```
|
||||
|
||||
## Ajout de nouveaux tests
|
||||
|
||||
Pour ajouter un test supplémentaire :
|
||||
|
||||
1. Incrémenter le compteur `ntest`
|
||||
2. Écrire la condition de test
|
||||
3. Logger le succès ou l'échec
|
||||
4. Incrémenter le bon compteur
|
||||
|
||||
```bash
|
||||
((ntest++))
|
||||
if ma_nouvelle_commande_de_test
|
||||
then
|
||||
log "Description du test: OK"
|
||||
((success++))
|
||||
else
|
||||
log "Description du test: failed"
|
||||
((failed++))
|
||||
fi
|
||||
```
|
||||
|
||||
## Comparaison avec d'autres tests
|
||||
|
||||
### Taille des données de test
|
||||
|
||||
| Commande | Taille des données | Nombre de fichiers |
|
||||
|----------|-------------------|-------------------|
|
||||
| obiconvert | 925 KB | 1 fichier |
|
||||
| obiuniq | ~600 bytes | 4 fichiers |
|
||||
| obimicrosat | 0 bytes | 0 fichiers (génère à la volée) |
|
||||
| **obisuperkmer** | **117 bytes** | **1 fichier** |
|
||||
|
||||
Notre test `obisuperkmer` est parmi les plus légers, ce qui est optimal pour CI/CD.
|
||||
|
||||
### Nombre de tests
|
||||
|
||||
| Commande | Nombre de tests |
|
||||
|----------|----------------|
|
||||
| obiconvert | 3 tests |
|
||||
| obiuniq | 7 tests |
|
||||
| obimicrosat | 1 test |
|
||||
| **obisuperkmer** | **12 tests** |
|
||||
|
||||
Notre test `obisuperkmer` offre une couverture complète avec 12 tests différents.
|
||||
|
||||
## Couverture de test
|
||||
|
||||
Les tests couvrent :
|
||||
|
||||
✅ Affichage de l'aide
|
||||
✅ Exécution basique
|
||||
✅ Paramètres par défaut (k=21, m=11)
|
||||
✅ Paramètres personnalisés (k=15, m=7)
|
||||
✅ Formats de sortie (FASTA)
|
||||
✅ Redirection vers fichier (`-o`)
|
||||
✅ Présence des métadonnées
|
||||
✅ Validation des IDs
|
||||
✅ Préservation des IDs parents
|
||||
✅ Cohérence des longueurs
|
||||
✅ Production de résultats non vides
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Mise à jour des tests
|
||||
|
||||
Si l'implémentation de `obisuperkmer` change :
|
||||
|
||||
1. Vérifier que les tests existants passent toujours
|
||||
2. Ajouter de nouveaux tests pour les nouvelles fonctionnalités
|
||||
3. Mettre à jour `README.md` si nécessaire
|
||||
4. Documenter les changements
|
||||
|
||||
### Vérification régulière
|
||||
|
||||
Exécuter périodiquement :
|
||||
|
||||
```bash
|
||||
cd obitests/obitools/obisuperkmer
|
||||
./test.sh
|
||||
```
|
||||
|
||||
Ou via l'ensemble des tests :
|
||||
|
||||
```bash
|
||||
cd obitests
|
||||
for dir in obitools/*/; do
|
||||
if [ -f "$dir/test.sh" ]; then
|
||||
echo "Testing $(basename $dir)..."
|
||||
(cd "$dir" && ./test.sh) || echo "FAILED: $(basename $dir)"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
Les tests pour `obisuperkmer` sont :
|
||||
|
||||
- ✅ **Complets** : 12 tests couvrant toutes les fonctionnalités principales
|
||||
- ✅ **Légers** : 117 bytes de données de test
|
||||
- ✅ **Rapides** : Exécution en quelques secondes
|
||||
- ✅ **Fiables** : Pattern éprouvé utilisé par toutes les commandes OBITools
|
||||
- ✅ **Maintenables** : Structure claire et documentée
|
||||
- ✅ **CI/CD ready** : Code de retour approprié et nettoyage automatique
|
||||
|
||||
Ils garantissent que la commande fonctionne correctement à chaque commit et facilitent la détection précoce des régressions.
|
||||
Reference in New Issue
Block a user