Skip to content

Commit 61ea24b

Browse files
pinin4fjordspinin4fjords
committed
Add things on naming
1 parent 92ee366 commit 61ea24b

File tree

1 file changed

+177
-48
lines changed

1 file changed

+177
-48
lines changed

‎docs/side_quests/nf-test.md‎

Lines changed: 177 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,22 @@ The `test` block is the actual test. It contains the following:
165165
- `when`: The conditions under which the test should be run. This includes the parameters that will be used to run the pipeline.
166166
- `then`: The assertions that should be made. This includes the expected outcomes of the pipeline.
167167

168+
### A Note on Test Names
169+
170+
In the example above, we used the name "Should run without failures" which is appropriate for a basic test that just checks if the pipeline runs successfully. However, as we add more specific test cases, we should use more descriptive names that indicate what we're actually testing. For example:
171+
172+
- "Should convert input to uppercase" - when testing specific functionality
173+
- "Should handle empty input gracefully" - when testing edge cases
174+
- "Should respect max memory parameter" - when testing resource constraints
175+
- "Should create expected output files" - when testing file generation
176+
177+
Good test names should:
178+
1. Start with "Should" to make it clear what the expected behavior is
179+
2. Describe the specific functionality or scenario being tested
180+
3. Be clear enough that if the test fails, you know what functionality is broken
181+
182+
As we add more assertions and specific test cases later, we'll use these more descriptive names to make it clear what each test is verifying.
183+
168184
In plain English, the logic of the test reads as follows:
169185
"**When** these _parameters_ are provided to this _pipeline_, **then** we expect to see these results."
170186

@@ -325,26 +341,46 @@ SUCCESS: Executed 1 tests in 5.239s
325341

326342
A simple check is to ensure our pipeline is running all the processes we expect and not skipping any silently. Remember our pipeline runs 6 processes, one called `sayHello` and one called `convertToUpper` for each of the 3 greetings.
327343

328-
Let's add an assertion to our test to check the pipeline runs the expected number of processes.
344+
Let's add an assertion to our test to check the pipeline runs the expected number of processes. We'll also update our test name to better reflect what we're testing.
329345

330346
**Before:**
331347

332348
```groovy title="tests/main.nf.test"
333-
then {
334-
assert workflow.success
335-
}
349+
test("Should run without failures") {
350+
351+
when {
352+
params {
353+
input_file = "${projectDir}/greetings.csv"
354+
}
355+
}
356+
357+
then {
358+
assert workflow.success
359+
}
360+
361+
}
336362
```
337363

338364
**After:**
339365

340366
```groovy title="tests/main.nf.test"
341-
then {
342-
assert workflow.success
343-
assert workflow.trace.tasks().size() == 6
344-
}
367+
test("Should run successfully with correct number of processes") {
368+
369+
when {
370+
params {
371+
input_file = "${projectDir}/greetings.csv"
372+
}
373+
}
374+
375+
then {
376+
assert workflow.success
377+
assert workflow.trace.tasks().size() == 6
378+
}
379+
380+
}
345381
```
346382

347-
The `workflow.trace` object includes information about the pipeline which we can check. In this case, we're checking the number of tasks is correct.
383+
The test name now better reflects what we're actually verifying - not just that the pipeline runs without failing, but that it runs the expected number of processes.
348384

349385
Let's run the test again to see if it works.
350386

@@ -360,40 +396,60 @@ https://www.nf-test.com
360396

361397
Test Workflow main.nf
362398

363-
Test [1d4aaf12] 'Should run without failures' PASSED (1.567s)
399+
Test [1d4aaf12] 'Should run successfully with correct number of processes' PASSED (1.567s)
364400

365401

366402
SUCCESS: Executed 1 tests in 1.588s
367403
```
368404

369-
Success! The pipeline runs successfully and the test passes. Now we have began to test the details of the pipeline. as well as the overall status.
405+
Success! The pipeline runs successfully and the test passes. Now we have began to test the details of the pipeline, as well as the overall status.
370406

371407
## 1.4. Test the output
372408

373-
Let's add an assertion to our test to check the output file was created.
409+
Let's add an assertion to our test to check the output file was created. We'll also update the test name again to reflect that we're now checking both process execution and output files.
374410

375411
**Before:**
376412

377413
```groovy title="tests/main.nf.test"
378-
then {
379-
assert workflow.success
380-
assert workflow.trace.tasks().size() == 6
381-
}
414+
test("Should run successfully with correct number of processes") {
415+
416+
when {
417+
params {
418+
input_file = "${projectDir}/greetings.csv"
419+
}
420+
}
421+
422+
then {
423+
assert workflow.success
424+
assert workflow.trace.tasks().size() == 6
425+
}
426+
427+
}
382428
```
383429

384430
**After:**
385431

386432
```groovy title="tests/main.nf.test"
387-
then {
388-
assert workflow.success
389-
assert workflow.trace.tasks().size() == 6
390-
assert file("$launchDir/results/Bonjour-output.txt").exists()
391-
assert file("$launchDir/results/Hello-output.txt").exists()
392-
assert file("$launchDir/results/Holà-output.txt").exists()
393-
assert file("$launchDir/results/UPPER-Bonjour-output.txt").exists()
394-
assert file("$launchDir/results/UPPER-Hello-output.txt").exists()
395-
assert file("$launchDir/results/UPPER-Holà-output.txt").exists()
396-
}
433+
test("Should run successfully with correct processes and output files") {
434+
435+
when {
436+
params {
437+
input_file = "${projectDir}/greetings.csv"
438+
}
439+
}
440+
441+
then {
442+
assert workflow.success
443+
assert workflow.trace.tasks().size() == 6
444+
assert file("$launchDir/results/Bonjour-output.txt").exists()
445+
assert file("$launchDir/results/Hello-output.txt").exists()
446+
assert file("$launchDir/results/Holà-output.txt").exists()
447+
assert file("$launchDir/results/UPPER-Bonjour-output.txt").exists()
448+
assert file("$launchDir/results/UPPER-Hello-output.txt").exists()
449+
assert file("$launchDir/results/UPPER-Holà-output.txt").exists()
450+
}
451+
452+
}
397453
```
398454

399455
Run the test again to see if it works.
@@ -412,7 +468,7 @@ https://www.nf-test.com
412468

413469
Test Workflow main.nf
414470

415-
Test [1d4aaf12] 'Should run without failures' PASSED (1.591s)
471+
Test [1d4aaf12] 'Should run successfully with correct processes and output files' PASSED (1.591s)
416472

417473

418474
SUCCESS: Executed 1 tests in 1.612s
@@ -534,15 +590,34 @@ Test Process sayHello
534590
FAILURE: Executed 1 tests in 4.884s (1 failed)
535591
```
536592

537-
The test fails because the `sayHello` process declares 1 input channel but 0 were specified. Let's fix that by adding an input to the process. Remember from part 1, our `sayHello` process takes a single value input.
593+
The test fails because the `sayHello` process declares 1 input channel but 0 were specified. Let's fix that by adding an input to the process. Remember from part 1, our `sayHello` process takes a single value input. We should also fix the test name to better reflect what we're testing.
538594

539595
**Before:**
540596

541597
```groovy title="tests/main.sayhello.nf.test"
542598
process {
543599
"""
544-
// define inputs of the process here. Example:
545-
// input[0] = file("test-file.txt")
600+
test("Should run without failures") {
601+
602+
when {
603+
params {
604+
// define parameters here. Example:
605+
// outdir = "tests/results"
606+
}
607+
process {
608+
"""
609+
// define inputs of the process here. Example:
610+
// input[0] = file("test-file.txt")
611+
"""
612+
}
613+
}
614+
615+
then {
616+
assert process.success
617+
assert snapshot(process.out).match()
618+
}
619+
620+
}
546621
"""
547622
}
548623
```
@@ -552,7 +627,27 @@ process {
552627
```groovy title="tests/main.sayhello.nf.test"
553628
process {
554629
"""
555-
input[0] = "hello"
630+
test("Should run without failures and produce correct output") {
631+
632+
when {
633+
params {
634+
// define parameters here. Example:
635+
// outdir = "tests/results"
636+
}
637+
process {
638+
"""
639+
input[0] = "hello"
640+
"""
641+
}
642+
}
643+
644+
then {
645+
assert process.success
646+
assert snapshot(process.out).match()
647+
}
648+
649+
}
650+
556651
"""
557652
}
558653
```
@@ -569,9 +664,9 @@ https://www.nf-test.com
569664

570665
Test Process sayHello
571666

572-
Test [f91a1bcd] 'Should run without failures' PASSED (1.604s)
667+
Test [f91a1bcd] 'Should run without failures and produce correct output' PASSED (1.604s)
573668
Snapshots:
574-
1 created [Should run without failures]
669+
1 created [Should run without failures and produce correct output]
575670

576671

577672
Snapshot Summary:
@@ -627,7 +722,7 @@ https://www.nf-test.com
627722

628723
Test Process sayHello
629724

630-
Test [f91a1bcd] 'Should run without failures' PASSED (1.675s)
725+
Test [f91a1bcd] 'Should run without failures and produce correct output' PASSED (1.675s)
631726

632727

633728
SUCCESS: Executed 1 tests in 1.685s
@@ -679,25 +774,59 @@ We now need to supply a single input file to the convertToUpper process, which i
679774
- We could re-use the existing data/greetings.csv file
680775
- We could create it on the fly within the test
681776

682-
For now, let's re-use the existing data/greetings.csv file using the example we used with the pipeline level test.
777+
For now, let's re-use the existing data/greetings.csv file using the example we used with the pipeline level test. As before, we can name the test to better reflect what we're testing.
683778

684779
**Before:**
685780

686781
```groovy title="tests/main.converttoupper.nf.test"
687-
process {
688-
"""
689-
// define inputs of the process here. Example:
690-
// input[0] = file("test-file.txt")
691-
"""
692-
}
782+
test("Should run without failures") {
783+
784+
when {
785+
params {
786+
// define parameters here. Example:
787+
// outdir = "tests/results"
788+
}
789+
process {
790+
"""
791+
// define inputs of the process here. Example:
792+
// input[0] = file("test-file.txt")
793+
"""
794+
}
795+
}
796+
797+
then {
798+
assert process.success
799+
assert snapshot(process.out).match()
800+
}
801+
802+
}
693803
```
694804

695805
**After:**
696806

697807
```groovy title="tests/main.converttoupper.nf.test"
698808
process {
699809
"""
700-
input[0] = "${projectDir}/greetings.csv"
810+
test("Should run without failures and produce correct output") {
811+
812+
when {
813+
params {
814+
// define parameters here. Example:
815+
// outdir = "tests/results"
816+
}
817+
process {
818+
"""
819+
input[0] = "${projectDir}/greetings.csv"
820+
"""
821+
}
822+
}
823+
824+
then {
825+
assert process.success
826+
assert snapshot(process.out).match()
827+
}
828+
829+
}
701830
"""
702831
}
703832
```
@@ -718,9 +847,9 @@ https://www.nf-test.com
718847

719848
Test Process convertToUpper
720849

721-
Test [c59b6044] 'Should run without failures' PASSED (1.755s)
850+
Test [c59b6044] 'Should run without failures and produce correct output' PASSED (1.755s)
722851
Snapshots:
723-
1 created [Should run without failures]
852+
1 created [Should run without failures and produce correct output]
724853

725854

726855
Snapshot Summary:
@@ -745,7 +874,7 @@ https://www.nf-test.com
745874

746875
Test Process convertToUpper
747876

748-
Test [c59b6044] 'Should run without failures' PASSED (1.798s)
877+
Test [c59b6044] 'Should run without failures and produce correct output' PASSED (1.798s)
749878

750879

751880
SUCCESS: Executed 1 tests in 1.811s
@@ -787,15 +916,15 @@ https://www.nf-test.com
787916

788917
Test Process convertToUpper
789918

790-
Test [c59b6044] 'Should run without failures' PASSED (1.798s)
919+
Test [c59b6044] 'Should run without failures and produce correct output' PASSED (1.798s)
791920

792921
Test Workflow main.nf
793922

794-
Test [1d4aaf12] 'Should run without failures' PASSED (1.652s)
923+
Test [1d4aaf12] 'Should run successfully with correct processes and output files' PASSED (1.652s)
795924

796925
Test Process sayHello
797926

798-
Test [f91a1bcd] 'Should run without failures' PASSED (1.664s)
927+
Test [f91a1bcd] 'Should run without failures and produce correct output' PASSED (1.664s)
799928

800929

801930
SUCCESS: Executed 3 tests in 5.007s

0 commit comments

Comments
 (0)