CLI

The CLI is how you can run Ply directly from the command line and also automatically as part of your continuous integration cycle. Running ply without any arguments will execute all requests/cases (except those that are ignored or skipped).

Installation

Install Ply through npm to use the CLI.

  1. Global
    npm install -g @ply-ct/ply
    

    This way you can run ply directly from the command line:

    ply --version
    
  2. Dev Dependency
    npm install --save-dev @ply-ct/ply
    

    Then you can run ply in your project directory through npx or an npm script:

    npx ply --version
    

    Command-line exercises in this guide assume you have Ply installed globally.

Command-Line Only Arguments

Option Default
-h Show help
--version, -v Show version number
--config, -c Specify path to plyconfig file (overrides default search mechanism)
--submit, -s Submit requests but don’t verify actual results against expected (ad hoc run)
--trusted Expressions are from trusted sources (otherwise safe evalation is performed with limited subset of template literal syntax)
--import Import requests or values from specified format. Currently ‘postman’ and ‘insomnia’ are supported formats. Overwrites existing same-named files.
--importToSuite Import collections into request suites (.yaml files), instead of individual (.ply) requests.
--report Generate report from from previously-executed Ply results. Valid values are json, csv, xlsx (see https://github.com/ply-ct/ply-viz for other formats).
--openapi Augment OpenAPI spec with Ply example requests/responses and code samples. Overwrites existing OpenAPI spec file.
--create Create expected result file from actual responses
--useDist Import case modules from build output (eg dist) instead of from TypeScript sources


Command-Line/Config Options

Option Default  
testsLocation
--testsLocation, -t
"." Tests base directory. Ply finds requests/cases/flows under here.
requestFiles
--requestFiles
"**\/*.{ply,ply.yaml,ply.yml}" Request files glob pattern, relative to testsLocation.
caseFiles
--caseFiles
"**\/*.ply.ts" Case files glob pattern, relative to testsLocation.
flowFiles
--flowFiles
"**\/*.flow" Flow files glob pattern, relative to testsLocation.
ignore
--ignore
"**\/{node_modules,bin,dist,out}\/**" File pattern to ignore, relative to testsLocation. Ignored files are not even parsed by Ply.
skip
--skip
"**\/*.ply" File pattern for requests/cases/flows that are loaded but shouldn’t be directly executed. By default, standalone requests (.ply files) are skipped by CLI test execution.
expectedLocation
--expectedLocation
testsLocation + "/results/expected" Base directory containing expected result files.
actualLocation
--actualLocation
testsLocation + "/results/actual" Base directory containing actual result files.
resultFollowsRelativePath
--resultFollowsRelativePath
true Result files live under a similar subpath as request/case files (eg: expected result relative to ‘expectedLocation’ is the same as request/case file relative to ‘testsLocation’). Otherwise results directory structure is flat.
logLocation
--logLocation
actualLocation Base directory for per-suite log files.
valuesFiles
--valuesFiles
  JSON files containing Ply values. Array in plyconfig, one comma-separated argument on the command line.
outputFile
--outputFile, -o
  For reporters, the report output file; otherwise specifies a JSON file summarizing Ply CLI results.
verbose
--verbose
false Display debug/verbose logging output. Takes precedence over ‘quiet’ if both are true.
quiet
--quiet
false The opposite of ‘verbose’. Only error/status output is logged.
bail
--bail
false Stop execution on first failure.
parallel
--parallel
false Run request/flow/case suites in parallel (but tests within a suite are always sequential).
batchRows
--batchRows
1 (For use with rowwise values). Number of rows to run per batch.
batchDelay
--batchDelay
0 (For use with rowwise values). Delay in ms between row batches.
reporter
--reporter
  Produce a report of results. Valid values are json, csv, xlsx (see https://github.com/ply-ct/ply-viz for other formats). Especially useful with rowwise values.
maxLoops
--maxLoops
10 (When flows have loopback links). Max instance count per step. Overridable in flow design.
responseBodySortedKeys
--responseBodySortedKeys
true Predictable ordering of response body JSON property keys in result files. Usually needed for verification.
genExcludeResponseHeaders
--genExcludeResponseHeaders
cache-control,
connection,
content-length,
date,
etag,
server,
transfer-encoding,
x-powered-by
Response headers to exclude when generating expected results.
prettyIndent
--prettyIndent
2 JSON format indenting for response body content in result files.

Examples

The following examples can be run by cloning the ply-demo project.

Run a request suite:

ply test/requests/movie-queries.ply.yaml

Run a single request:

ply test/requests/movie-queries.ply.yaml#moviesByYearAndRating

Run a case suite:

ply test/cases/movieCrud.ply.ts

Run a single case:

ply "test/cases/movieCrud.ply.ts#add new movie"

Next Topic: Config