From 43a895fe2931b317bff7b94fee976864bcefe279 Mon Sep 17 00:00:00 2001 From: "James A. Fellows Yates" Date: Fri, 11 Oct 2024 11:23:26 +0200 Subject: [PATCH 1/2] Make docs for getAllFilesInDir() user readable --- docs/usage.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 00e199b..2097484 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -64,7 +64,13 @@ The first argument is path to the YAML file, the second and third arguments are ## `getAllFilesFromDir()` -This function generates a list of all the contents within a directory, allowing for the exclusion of specific files using a glob pattern. It can be used to obtain filenames alone, enabling snapshotting of just the names when the content is not stable. Alternatively, it can snapshot the entire list of files with stable content. +This function generates a list of all the contents within a directory (and subdirectories), additionally allowing for the inclusion or exclusion of specific files using glob patterns. + +- The first argument is the directory path to screen for file paths (e.g. a pipeline’s `outdir` ). +- The second argument is a boolean indicating whether to include subdirectory names in the list. +- The third argument is a _list_ of glob patterns to exclude. +- The fourth argument is a _file_ containing additional glob patterns to exclude. +- The fifth argument is a _list_ of glob patterns to include. In this example, below are the files produced by a pipeline: @@ -79,31 +85,36 @@ results/ 2 directories, 3 files ``` -In this example, 1 file is stable with stable content (`stable_content.txt`), and 1 file is stable with a stable name (`stable_name.txt`). -The last file has no stable content (`execution_trace_2024-09-30_13-10-16.txt`) as its name is based on the date and time of the pipeline execution. +One file has stable content and a stable name (`stable_content.txt`), and one file has unstable contents but a stable name (`stable_name.txt`). +The last file (`execution_trace_2024-09-30_13-10-16.txt`) has no stable content nor a stable name, as its name is based on the date and time of the pipeline execution. + +We aim to snapshot files with stable content, and stable names (for both files and directories), but excluding the completely unstable file. + +First, we will specify the following two variables that we will pass to the nf-test snapshot function: + +- The `stable_name` variable contains a list of all files and directories, excluding those matching the glob pattern `pipeline_info/execution_*.{html,txt}` (i.e., the unstable file). +- The `stable_content` variable contains a list of all files, excluding those that match the two glob patterns: `pipeline_info/execution_*.{html,txt}` and `**/stable_name.txt`. + - The latter is specified in the `tests/getAllFilesFromDir/.nftignore` file. + +```groovy +def stable_name = getAllFilesFromDir(params.outdir, true, ['pipeline_info/execution_*.{html,txt}'], null, ['*', '**/*']) +def stable_content = getAllFilesFromDir(params.outdir, false, ['pipeline_info/execution_*.{html,txt}'], 'tests/getAllFilesFromDir/.nftignore', ['*', '**/*']) +``` -In this example, we aim to snapshot files with stable content, along with the names of files and folders that are stable. +Secondly, we need to supply these two variables to the nf-test snapshot assrtion. +The list of files in `stable_content` can be supplied to the snapshot directly, and nf-test will include the md5sum hash of the file contents. +For the list of stable file names with unstable contents, we can use `stable_name*.name`, to just extract just _name_ of every file in the list for comparison (i.e., without generating the md5sum hash). -•`stable_name` is a list of all files and folders, excluding those matching the glob pattern `pipeline_info/execution_*.{html,txt}`. -•`stable_content` is a list of all files, excluding those that match the two glob patterns: `pipeline_info/execution_*.{html,txt}` and `**/stable_name.txt`. The latter is specified in the `tests/getAllFilesFromDir/.nftignore` file. -By using `stable_name*.name`, we extract the name of every file in `stable_name` and add them to the snapshot. -`stable_content` can be used in the snapshot directly to include the hash of the file contents. ```groovy def stable_name = getAllFilesFromDir(params.outdir, true, ['pipeline_info/execution_*.{html,txt}'], null, ['*', '**/*']) def stable_content = getAllFilesFromDir(params.outdir, false, ['pipeline_info/execution_*.{html,txt}'], 'tests/getAllFilesFromDir/.nftignore', ['*', '**/*']) assert snapshot( - stable_name*.name, stable_content + stable_name*.name, ).match() ``` -• The first argument is the pipeline’s `outdir` directory path. -• The second argument is a boolean indicating whether to include folders. -• The third argument is a list of glob patterns to ignore. -• The fourth argument is a file containing additional glob patterns to ignore. -• The fifth argument is a list of glob patterns to include. - `getAllFilesFromDir()` also supports named parameters: ```groovy From 35a200c4c370047c8de32bb672d28ae4d24dba30 Mon Sep 17 00:00:00 2001 From: "James A. Fellows Yates" Date: Fri, 11 Oct 2024 11:30:18 +0200 Subject: [PATCH 2/2] Update docs/usage.md Co-authored-by: Maxime U Garcia --- docs/usage.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/usage.md b/docs/usage.md index 2097484..33a7af9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -71,6 +71,7 @@ This function generates a list of all the contents within a directory (and subdi - The third argument is a _list_ of glob patterns to exclude. - The fourth argument is a _file_ containing additional glob patterns to exclude. - The fifth argument is a _list_ of glob patterns to include. +- The sixth argument is a boolean indicating whether to output relative paths. In this example, below are the files produced by a pipeline: