From bb7307e31451dea2259aa677830ec3f780666293 Mon Sep 17 00:00:00 2001
From: awileysnyk <95229836+awileysnyk@users.noreply.github.com>
Date: Tue, 14 Dec 2021 14:29:58 -0500
Subject: [PATCH] docs: update test command help
---
help/cli-commands/test.md | 254 +++++++++++++++-----------------------
1 file changed, 98 insertions(+), 156 deletions(-)
diff --git a/help/cli-commands/test.md b/help/cli-commands/test.md
index 4ab76b3516a..e6661986856 100644
--- a/help/cli-commands/test.md
+++ b/help/cli-commands/test.md
@@ -1,4 +1,4 @@
-# snyk test -- test local project for vulnerabilities
+# snyk test -- test a project for open source vulnerabilities and license issues
## Usage
@@ -6,33 +6,52 @@
## Description
-Test command checks locally installed projects for vulnerabilities. It tries to autodetect supported manifest files with dependencies and test those.
+The `snyk test` command checks projects for open source vulnerabilities and license issues. The test command tries to auto-detect supported manifest files with dependencies and test those.
+
+## Exit codes
+
+Possible exit codes and their meaning:
+
+**0**: success, no vulnerabilities found
+**1**: action_needed, vulnerabilities found
+**2**: failure, try to re-run command
+**3**: failure, no supported projects detected
+
+## Configure the Snyk CLI
+
+You can use environment variables to configure the Snyk CLI and also set variables to configure the Snyk CLI to connect with the Snyk API. See [Configure the Snyk CLI](https://docs.snyk.io/features/snyk-cli/configure-the-snyk-cli).
+
+## Debug
+
+Use the `-d` option to output the debug logs.
## Options
-To see command-specific flags and usage, see `help` command, e.g. `snyk container --help`.
-For advanced usage, we offer language and context specific flags, listed further down this document.
+See also subsequent sections for options for specific build environments, package managers, languages, and `[]` which you specify last.
### `--all-projects`
-Auto-detect all projects in working directory
+Auto-detect all projects in the working directory.
### `--detection-depth=`
-Use with --all-projects or --yarn-workspaces to indicate how many sub-directories to search. `DEPTH` must be a number.
+Use with options as documented to indicate how many sub-directories to search. `DEPTH` must be a number.
+
+Default: 4 (the current working directory and 3 sub-directories).
-Default: 4 (the current working directory and 3 sub-directories)
+Example: `--detection-depth=3` limits search to the specified directory (or the current directory if no `` is specified) plus three levels of subdirectories.
### `--exclude=[,]...>`
-Can be used with --all-projects and --yarn-workspaces to indicate sub-directories and files to exclude. Must be comma separated.
+Can be used with `--all-projects` and `--yarn-workspaces` to indicate sub-directories and files to exclude. Must be comma separated.
-If using with `--detection-depth` exclude ignores directories at any level deep.
+Use the exclude option with `--detection-depth` to ignore directories at any depth.
### `--prune-repeated-subdependencies`, `-p`
Prune dependency trees, removing duplicate sub-dependencies.
-Will still find all vulnerabilities, but potentially not all of the vulnerable paths.
+
+Continues to find all vulnerabilities, but may not find all of the vulnerable paths.
### `--print-deps`
@@ -44,42 +63,42 @@ Set or override the remote URL for the repository that you would like to monitor
### `--dev`
-Include development-only dependencies. Applicable only for some package managers. E.g. _devDependencies_ in npm or _:development_ dependencies in Gemfile.
+Include development-only dependencies. Applicable only for some package managers, for example `devDependencies` in npm or `:development` dependencies in Gemfile.
-Default: scan only production dependencies
+Default: scan only production dependencies.
### `--org=`
-Specify the to run Snyk commands tied to a specific organization. This will influence where will new projects be created after running `monitor` command, some features availability and private tests limits.
+Specify the to run Snyk commands tied to a specific organization. The influences some features availability and private test limits.
+
If you have multiple organizations, you can set a default from the CLI using:
`$ snyk config set org=`
-Setting a default will ensure all newly monitored projects will be created
-under your default organization. If you need to override the default, you can use the `--org=`argument.
+Set a default to ensure all newly tested projects are tested under your default organization. If you need to override the default, use the `--org=` option.
-Default: uses `` that sets as default in your [Account settings](https://app.snyk.io/account)
+Default: `` that is the current preferred organization in your [Account settings](https://app.snyk.io/account).
### `--file=`
-Sets a package file.
+Specify a package file.
-When testing locally or monitoring a project, you can specify the file that Snyk should inspect for package information. When ommitted Snyk will try to detect the appropriate file for your project.
+When testing locally or monitoring a project, you can specify the file that Snyk should inspect for package information. When the file is not specified, Snyk tries to detect the appropriate file for your project.
### `--ignore-policy`
-Ignores all set policies. The current policy in `.snyk` file, Org level ignores and the project policy on snyk.io.
+Ignore all set policies, the current policy in the `.snyk` file, Org level ignores, and the project policy on snyk.io.
-### `--trust-policies`
+### `--org=`
-Applies and uses ignore rules from your dependencies' Snyk policies, otherwise ignore policies are only shown as a suggestion.
+Apply and use ignore rules from the Snyk policies your dependencies; otherwise ignore rules in the dependencies are only shown as a suggestion.
-### `--show-vulnerable-paths`=none|some|all
+### `--show-vulnerable-paths=none|some|all`
-Display the dependency paths from the top level dependencies, down to the vulnerable packages. Doesn't affect output when using JSON `--json` output.
+Display the dependency paths from the top level dependencies down to the vulnerable packages. Does not affect output when using JSON `--json` output.
-Default: (a few example paths shown)
- is an alias for .
+Default: `some` (a few example paths shown).
+`false` is an alias for `none`.
### `--project-name=`
@@ -87,24 +106,21 @@ Specify a custom Snyk project name.
### `--target-reference=`
-A reference which differentiates this project. For example, a branch name or version. Projects using the same reference can be used for grouping. Only supported for Snyk Open Source. [More information](https://snyk.info/3B0vTPs).
-
-### `--tags=[,]...>`
-
-This is an alias for `--project-tags`.
+Specify a reference which differentiates this project, for example, a branch name or version. Projects having the same reference can be grouped based on that reference. Only supported for Snyk Open Source. For more information see [Separating projects by branch or version](https://snyk.info/3B0vTPs).
### `--policy-path=`
-Manually pass a path to a snyk policy file.
+Manually pass a path to a `.snyk` policy file.
### `--json`
-Prints results in JSON format.
+Print results in JSON format.
### `--json-file-output=`
Save test output in JSON format directly to the specified file, regardless of whether or not you use the `--json` option.
-This is especially useful if you want to display the human-readable test output via stdout and at the same time save the JSON format output to a file.
+
+This is especially useful if you want to display the human-readable test output using stdout and at the same time save the JSON format output to a file.
### `--sarif`
@@ -113,204 +129,130 @@ Return results in SARIF format.
### `--sarif-file-output=`
Save test output in SARIF format directly to the file, regardless of whether or not you use the `--sarif` option.
-This is especially useful if you want to display the human-readable test output via stdout and at the same time save the SARIF format output to a file.
+
+This is especially useful if you want to display the human-readable test output using stdout and at the same time save the SARIF format output to a file.
### `--severity-threshold=low|medium|high|critical`
-Only report vulnerabilities of provided level or higher.
+Report only vulnerabilities at the specified level or higher.
### `--fail-on=all|upgradable|patchable`
-Only fail when there are vulnerabilities that can be fixed.
+Fail only when there are vulnerabilities that can be fixed.
-- `all`: fails when there is at least one vulnerability that can be either upgraded or patched.
-- `upgradable`: fails when there is at least one vulnerability that can be upgraded.
-- `patchable`: fails when there is at least one vulnerability that can be patched.
+- `all`: fail when there is at least one vulnerability that can be either upgraded or patched.
+- `upgradable`: fail when there is at least one vulnerability that can be upgraded.
+- `patchable`: fail when there is at least one vulnerability that can be patched.
-If vulnerabilities do not have a fix and this option is being used, tests will pass.
+If vulnerabilities do not have a fix and this option is being used, tests pass.
-### `-- []`
+## Options for Maven projects
-Pass extra arguments directly to Gradle or Maven.
-E.g. `snyk test -- --build-cache`
+For more information about Maven CLI options see [Snyk for Java (Gradle, Maven)](https://docs.snyk.io/products/snyk-open-source/language-and-package-manager-support/snyk-for-java-gradle-maven).
-Below are flags that are influencing CLI behavior for specific projects, languages and contexts:
+### `--scan-all-unmanaged`
-### Maven options
+Auto-detect maven jars, aars, and wars in given directory. To test individually use `--file=`.
-#### `--scan-all-unmanaged`
+### `--reachable`
-Auto detects maven jars, aars, and wars in given directory. Individual testing can be done with `--file=`
+Analyze your source code to find which vulnerable functions and packages are called.
-#### `--reachable`
+### `--reachable-timeout=`
-Analyze your source code to find which vulnerable
-functions and packages are called.
-
-#### `--reachable-timeout=`
-
-The amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than , Reachable Vulnerabilities are not reported. This does not affect regular test or monitor output.
+Specify the amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than ``, reachable vulnerabilities are not reported. This does not affect regular test or monitor output.
Default: 300 (5 minutes).
-### Gradle options
+## Options for Gradle projects
-[More information about Gradle CLI options](https://snyk.co/ucT6P)
+For more information about Gradle CLI options see [Snyk for Java (Gradle, Maven)](https://docs.snyk.io/products/snyk-open-source/language-and-package-manager-support/snyk-for-java-gradle-maven).
-#### `--sub-project=`, `--gradle-sub-project=`
+### `--sub-project=`, `--gradle-sub-project=`
For Gradle "multi project" configurations, test a specific sub-project.
-#### `--all-sub-projects`
+### `--all-sub-projects`
For "multi project" configurations, test all sub-projects.
-#### `--configuration-matching=`
+### `--configuration-matching=`
-Resolve dependencies using only configuration(s) that match the provided Java regular expression, e.g. `^releaseRuntimeClasspath$`.
+Resolve dependencies using only configuration(s) that match the specified Java regular expression, for example, `^releaseRuntimeClasspath$`.
-#### `--configuration-attributes=[,]...`
+### `--configuration-attributes=[,]...`
-Select certain values of configuration attributes to resolve the dependencies. E.g. `buildtype:release,usage:java-runtime`
+Select certain values of configuration attributes to install dependencies and perform dependency resolution, for example, `buildtype:release,usage:java-runtime`.
-#### `--reachable`
+### `--reachable`
-Analyze your source code to find which vulnerable
-functions and packages are called.
+Analyze your source code to find which vulnerable functions and packages are called.
-#### `--reachable-timeout=`
+### `--reachable-timeout=`
-The amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than , Reachable Vulnerabilities are not reported. This does not affect regular test or monitor output.
+Specify the amount of time (in seconds) to wait for Snyk to gather reachability data. If it takes longer than ``, reachable vulnerabilities are not reported. This does not affect regular test or monitor output.
Default: 300 (5 minutes).
-#### `--init-script=`
+### `--project-name-prefix=`
-When monitoring a .NET project, use this flag to add a custom prefix to the name of files inside a project along with any desired separators, e.g. `snyk monitor --file=my-project.sln --project-name-prefix=my-group/`. This is useful when you have multiple projects with the same name in other sln files.
+When monitoring a .NET project, use this option to add a custom prefix to the name of files inside a project along with any desired separators, for example, `snyk monitor --file=my-project.sln --project-name-prefix=my-group/`. This is useful when you have multiple projects with the same name in other `.sln` files.
-### npm options
+## Options for npm projects
-#### `--strict-out-of-sync=true|false`
+### `--strict-out-of-sync=true|false`
Control testing out of sync lockfiles.
Default: true
-### Yarn options
+## Options for Yarn projects
-#### `--strict-out-of-sync=true|false`
+### `--strict-out-of-sync=true|false`
Control testing out of sync lockfiles.
Default: true
-#### `--yarn-workspaces`
+### `--yarn-workspaces`
Detect and scan yarn workspaces. You can specify how many sub-directories to search using `--detection-depth` and exclude directories and files using `--exclude`.
-### CocoaPods options
+## Options for CocoaPods projects
-#### `--strict-out-of-sync=true|false`
+### `--strict-out-of-sync=true|false`
Control testing out of sync lockfiles.
Default: false
-### Python options
+## Options for Python projects
-#### `--command=`
+### `--command=`
-Indicate which specific Python commands to use based on Python version. The default is `python` which executes your systems default python version. Run 'python -V' to find out what version is it. If you are using multiple Python versions, use this parameter to specify the correct Python command for execution.
+Indicate which specific Python commands to use based on Python version. The default is `python` which executes your default python version. Run 'python -V' to find out what version it is. If you are using multiple Python versions, use this parameter to specify the correct Python command for execution.
Default: `python`
Example: `--command=python3`
-#### `--skip-unresolved`=true|false
+### `--skip-unresolved=true|false`
Allow skipping packages that are not found in the environment.
-### Flags available accross all commands
-
-#### `--insecure`
-
-Ignore unknown certificate authorities.
-
-#### `-d`
-
-Output debug logs.
-
-#### `--quiet`, `-q`
-
-Silence all output.
-
-#### `--version`, `-v`
-
-Prints versions.
+## `-- []`
-#### `--help []`, `[] --help`, `-h`
-
-Prints a help text. You may specify a `` to get more details.
-
-## Environment
-
-You can set these environment variables to change CLI settings.
-
-### `SNYK_TOKEN`
-
-Snyk authorization token. Setting this envvar will override the token that may be available in your `snyk config` settings.
-
-[How to get your account token](https://snyk.co/ucT6J)
-[How to use Service Accounts](https://snyk.co/ucT6L)
-
-### `SNYK_CFG_KEY`
-
-Allows you to override any key that's also available as `snyk config` option.
-
-E.g. `SNYK_CFG_ORG=myorg` will override default org option in `config` with "myorg".
-
-### `SNYK_REGISTRY_USERNAME`
-
-Specify a username to use when connecting to a container registry. Note that using the `--username` flag will override this value. This will be ignored in favour of local Docker binary credentials when Docker is present.
-
-### `SNYK_REGISTRY_PASSWORD`
-
-Specify a password to use when connecting to a container registry. Note that using the `--password` flag will override this value. This will be ignored in favour of local Docker binary credentials when Docker is present.
-
-### Connecting to Snyk API
-
-By default Snyk CLI will connect to `https://snyk.io/api/v1`.
-
-#### `SNYK_API`
-
-Sets API host to use for Snyk requests. Useful for on-premise instances and configuring proxies. If set with `http` protocol CLI will upgrade the requests to `https`. Unless `SNYK_HTTP_PROTOCOL_UPGRADE` is set to `0`.
-
-#### `SNYK_HTTP_PROTOCOL_UPGRADE=0`
-
-If set to the value of `0`, API requests aimed at `http` URLs will not be upgraded to `https`. If not set, the default behavior will be to upgrade these requests from `http` to `https`. Useful e.g., for reverse proxies.
-
-#### `HTTPS_PROXY` and `HTTP_PROXY`
-
-Allows you to specify a proxy to use for `https` and `http` calls. The `https` in the `HTTPS_PROXY` means that _requests using `https` protocol_ will use this proxy. The proxy itself doesn't need to use `https`.
-
-## Exit codes
-
-Possible exit codes and their meaning:
-
-**0**: success, no vulns found
-**1**: action_needed, vulns found
-**2**: failure, try to re-run command
-**3**: failure, no supported projects detected
+Use context-specific options to pass extra arguments directly to Gradle, Maven, or other build tools. These options are specified last. Example: `snyk test -- --build-cache`