Lunch Money API Tests

This repository contains test configurations for the Lunch Money v2 API. Lunch Money is a delightfully simple personal finance and budgeting tool with a comprehensive developer API.

Installation

Install the package:

npm install @lunch-money/v2-api-tests

The package includes a dependency on @lunch-money/v2-api-spec, which provides the OpenAPI specification. The spec will be automatically installed as a dependency.

How the tests work

The tests are generated by Portman, which is installed as a dependency.

Portman reads the OpenAPI specification from @lunch-money/v2-api-spec (also installed as a dependency) and generates a Postman collection with a set of requests designed to exercise the API.

You do not need to have Postman installed to run the tests, as Portman includes the Postman CLI tool Newman which it can use to execute the requests. It is handy to have Postman when tests fail and you want to see the tests and/or rerun a single request during an interactive debugging process.

This package also installs a proxy tool called Inspectr. When run with this proxy, the API responses can be viewed in a browser, which is useful for determining why a test failed.

Configuration Files

The following files define Portman behavior:

portman-cli.json

This file sets the Portman CLI options used for the tests. In general, it does not need to be modified.

Local Environment Configuration

A .env-portman file can be used to specify how Portman can push the generated Postman collection to a hosted Postman instance (not required, but useful for troubleshooting tests), as well as setting any environment-specific collection variables which influence how the tests are run.

To set up your own environment variables, copy the env-portman.template file to the root directory of the project that implements the Lunch Money API and name the file .env-portman. Ensure that this file is in your .gitignore so that it is not committed to any repos as it will contain secrets.

You may then edit this file to set the following:

• PORTMAN_BEARER_TOKEN=12345678901 - Specify an access token for a budget to test against.
• PORTMAN_USER_NAME - The name of the user associated with the token. This is used by the GET /me tests.
• PORTMAN_USER_EMAIL - The email of the user associated with the token. Also used by the GET /me tests.
• PORTMAN_IS_MOCK_SERVICE - set to true when running tests against the v2-docs-and-mock API service.

In general the PORTMAN_ directive creates Postman collection environment variables converting everything after PORTMAN_ into a lower snake case name. For example PORTMAN_IS_MOCK_SERVER=true, will set a Postman collection variable isMockServer to true. You can use this to set any postman collection variables you want.

Optionally you can also set the following two environment variables: POSTMAN_API_KEY - set this to the API key for your Postman instance POSTMAN_WORKSPACE_NAME - set this to the name of the workspace in Postman that you want to write the generated test collection to.

These last two are only necessary if the cli configuration option "syncPostman" is set to true.

If you choose not to have Portman automatically upload the generated collection to Postman, you can also manually import the generated collection into Postman by choosing File/Import and then selecting the generated collection, which our configuration specifies is written to: node_modules/@lunch-money/v2-api-tests/generated/portman-generated-tests.json

portman-config.yaml

This is the configuration file that defines which tests to generate.

Usage

Add the following to scripts to your package.json to use this package:

• Generate and run the tests in a single pass

    "run-tests": "npx portman --cliOptionsFile node_modules/@lunch-money/v2-api-tests/portman-cli.json --baseUrl ${TEST_URL:-http://localhost:3002/v2}",

• Generate the variation tests only

    "gen-tests": "npx portman --cliOptionsFile node_modules/@lunch-money/v2-api-tests/portman-cli.json --runNewman=false --syncPostman=false && node_modules/@lunch-money/v2-api-tests/scripts/extract-integration-tests.sh",

• Run previously generated tests

  "run-generated-tests": "npx newman run node_modules/@lunch-money/v2-api-tests/generated/portman-generated-tests.json --bail --env-var baseUrl=${TEST_URL:-http://localhost:3000/v2} | tee node_modules/@lunch-money/v2-api-tests/generated/newman.out && node_modules/@lunch-money/v2-api-tests/scripts/check-for-skipped.sh",

• Start the Inspectr proxy (useful for seeing the response on failed tests)

    "start-inspectr": "npx @inspectr/inspectr --backend=${REDIRECT_URL:-http://localhost:3000} &",

• Run previously generated tests through inspectr proxy

    "run-inspectr-tests": "npx newman run node_modules/@lunch-money/v2-api-tests/generated/integration-tests-only.json --bail --env-var baseUrl=http://localhost:8080/v2 | tee node_modules/@lunch-money/v2-api-tests/generated/newman.out && node_modules/@lunch-money/v2-api-tests/scripts/check-for-skipped.sh",

Testing Against a Mock Service vs a Real Service

By default, the tests will take the ID of the last queried or created object (e.g., a category or a transaction) and use that on subsequent GET/PUT/DELETE tests. This approach generally works for real APIs, and the tests tend to "clean up" any data created during the testing process.

When running against a mock service with immutable data, this is not the desired behavior. Instead, we want to use IDs that are taken from the examples defined in the OpenAPI spec.

Adding the following line to the .env-portman file will make the tests work when applied against mock servers:

# If pre-skipIfProxyService.js=="true", dynamic IDs are not used in "*::/*/{id}" requests
PORTMAN_IS_MOCK_SERVICE=true

You can also optionally add the IDs that you want to use when isMockServer is true by adding the following in the .env-portman:

### IDS TO USE WHEN CALLING AN ENDPOINT WITH A ID PATH PARAM WITH A MOCK SERVER
PORTMAN_CATEGORIES_MOCK_ID=83

This will instruct Portman to use the id 83 for all GET/PUT/DELETE queries. If this is not set, a hardcoded value will be used based on the examples in the OpenAPI spec.