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
--values Runtime override values. For example: --values title=Dracula tmdb.studio=33 => { "title": "Dracula", "tmdb": { "studio": 33 } }. Should be last option if specified.
--stepsBase Base file system location for custom flow steps


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		 "**/*.ply.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 (relative to testsLocation). 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.
validate
--validate		 true unless 'submit' Validate flow input values.
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,
keep-alive,
server,
transfer-encoding,
x-powered-by		 Response headers to exclude when generating expected results.
binaryMediaTypes
--binaryMediaTypes		 application/octet-stream,
image/png,
image/jpeg,
image/gif,
application/pdf		 Media types to be treated as binary responses. Base64 encoded in result yaml files.
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 from a suite:

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

Run a request from a .ply file:

ply test/requests/create-movie.ply

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