Nihilism Philisophy Major

    This package has been deprecated

    Author message:

    Please upgrade to @ply-ct/ply

    ply-ct
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.15 • Public • Published
    ply-logo

    API Automated Testing

    Installation

    npm install ply-ct --save-dev
    

    Or, to run anywhere:

    npm install -g ply-ct
    

    Usage

    Ply API testing starts with a YAML file containing requests. Here's a GET request to retrieve topics for the ply-demo repository using GitHub API v3:

    repositoryTopics:
      url: 'https://api.github.com/repos/ply-ct/ply-demo/topics'
      method: GET
      headers:
        Accept: application/vnd.github.mercy-preview+json

    Run a request

    Suppose you save this in a file named "github.ply.yml". Then you can submit the repositoryTopics request from a command line by typing:

    ply -s github.ply.yml
    

    The -s argument tells Ply not to verify the response (-s is short for --submit, meaning submit an ad hoc request and don't bother with verification).

    Verify response

    If you run without -s you'll get an error saying, "Expected result file not found". Ply verification works by comparing expected vs actual. So a complete test requires an expected result file. Run again with --create, and the expected result file will be created from the actual response.

    ply --create github.ply.yml
    

    Output looks like this:

    Request 'repositoryTopics' submitted at 8/28/2020, 10:54:40:667
    Creating expected result: ./results/expected/github.yml
    Test 'repositoryTopics' PASSED in 303 ms
    

    During execution Ply submits the request and writes actual result file "./results/actual/github.yml" based on the response. Because of --create, Ply then copies the actual result over expected result file "./results/expected/github.yml" before comparing. This test naturally passes since the results are identical.

    Expected results

    Auto-creating an expected result provides a good starting point. But looking at "./results/expected/github.yml", you'll notice that it includes many response headers that are not of interest for testing purposes. Here's a cleaned-up version of similar expected results from ply-demo:

    repositoryTopics:
      request:
        url: 'https://api.github.com/repos/${github.organization}/${github.repository}/topics'
        method: GET
        headers:
          Accept: application/vnd.github.mercy-preview+json
      response:
        status:
          code: 200
          message: OK
        headers:
          content-type: application/json; charset=utf-8
          status: 200 OK
        body: |-
          {
            "names": [
              "rest-api",
              "testing",
              "ply",
              "example-project",
              "graphql",
              "typescript",
              "github-workflow"
            ]
          }

    The subset of response headers included in expected results YAML are those we care about for comparison. In this test, body content is our main concern.

    Expressions

    Something else about this example may be noticed by sharp-eyed observers: our request URL contains placeholders like ${github.organization}. Ply supports JavaScript template literal syntax for substituting dynamic values in both requests and results. Values come from JSON files and/or environment variables, as described in the docs under Values.

    Even more powerfully, your multi-request suites can embed expressions that reference runtime values from previous responses. For instance, the URL or body of a subsequent request in our github.ply.yml file could have something like this:

    ${@repositoryTopics.response.body.names[0]}
    

    which uses the special @ character to reference the first topic name from above (resolving to 'rest-api'). This enables you to string together sequential requests that each depend on response output from preceding ones. Check out the Results topic for details and examples.

    Cases

    For complex testing scenarios, you'll want even greater control over request execution. Implement a Ply case suite using TypeScript for programmatic access to your requests/responses. Here's add new movie from ply-demo:

    @test('add new movie')
    async createMovie(values: any) {
        const result = await this.requestSuite.run('createMovie', values);
        assert.exists(result.response);
        assert.exists(result.response?.body);
        // capture movie id from response -- used in downstream values
        this.movieId = result.response?.body?.id;
        this.requestSuite.log.info(`Created movie: id=${this.movieId}`);
    }

    Applying the @test decorator to a method automatically makes it a Ply case. At this point this.requestSuite has already been loaded from request YAML (in the case suite's constructor):

    this.requestSuite = ply.loadSuiteSync('test/requests/movies-api.ply.yaml');

    Then in createMovie() above, the request named 'createMovie' from movies-api.ply.yaml is invoked by calling Ply's API method Suite.run().

    Running a case suite from the command line is similar to running a request suite:

    ply test/cases/movieCrud.ply.ts
    

    This executes all cases in movieCrud.ply.ts (in the order they're declared), and compiles actual results from all requests into a file named after the @suite ("movie-crud.yaml"). At the end of the run, actual results are compared against expected to determine whether the suite has passed.

    GraphQL

    Body content in request YAML can be any text payload (typically JSON). GraphQL syntax is also supported, as in this example which queries the GitHub GraphQL API for ply-demo repository topics:

    repositoryTopicsQuery:
      url: 'https://api.github.com/graphql'
      method: POST
      headers:
        Authorization: Bearer ${githubToken}
        Content-Type: application/json
        User-Agent: ${github.organization}
      body: |-
        query {
          repository(owner: "${github.organization}", name: "${github.repository}") {
            repositoryTopics(first: 10) {
              edges {
                node {
                  topic {
                    name
                  }
                }
              }
            }
          }
        }

    Documentation

    Guide

    https://ply-ct.github.io/ply/

    API

    https://ply-ct.github.io/ply/api

    Demo Project

    https://github.com/ply-ct/ply-demo/

    VS Code Extension

    https://marketplace.visualstudio.com/items?itemName=ply-ct.vscode-ply

    Install

    npm i ply-ct

    DownloadsWeekly Downloads

    21

    Version

    3.0.15

    License

    MIT

    Unpacked Size

    473 kB

    Total Files

    132

    Last publish

    Collaborators

    • donoakes
    • ply-org
    • rich_tq_1