Consumer-Driven Contract Testing (CDCT) shifts the responsibility for integration testing from the provider to the consumers. Under this model, providers can freely update their services as long as the changes continue to pass tests defined by consumers. These tests, acting as contracts, specify the conditions the API must meet. If a provider’s update causes a consumer’s service to fail and this failure is due to gaps in the consumer-defined tests, the responsibility lies with the consumer.

In the Postman ecosystem, multiple consumers can generate and manage collections of tests that define their interactions with an API. These collections allow providers to verify that changes to the API will not break existing consumer integrations.

Features

  • Integration Testing: Allows for the validation of API responses, ensuring successes and errors are handled correctly.
  • Sequential Request Execution: Supports the chaining of requests, utilizing the output from one API call as input for another.
  • Automation Capabilities: Newman, the headless version of Postman, functions effectively in CI/CD pipelines.
  • Customizable Environment Configuration: Enables the setup of multiple environments, each customizable with specific variables.
  • Mock Servers: Simulates backend services, allowing for early feedback from consuming services.

Collaborative Features in Postman’s Ecosystem:

  • Shared Collections: Facilitates version-controlled sharing of API requests and tests among team members.
  • Team Workspaces: Provides spaces for teams to collectively manage API resources, including collections, environments, and documentation.
  • Automatic Documentation: Generates and publishes documentation dynamically.

Integration Testing

Add the database to the docker-compose.yml to ensure a reliable and predictable testing environment.

game_db_integration:
  image: postgres
  environment:
    POSTGRES_DB: game_db_integration
    POSTGRES_USER: integration_user
    POSTGRES_PASSWORD: integration_password
  ports:
    - "5483:5432"
  networks:
    - test_network

Although Newman can be downloaded and run locally, I prefer to interact with it via Docker by adding it to docker-compose.yml.

newman:
  image: postman/newman:latest
  volumes:
    - ./test_postman:/etc/newman
  working_dir: /etc/newman
  entrypoint: sh
  command: -c "./run_newman.sh"
  networks:
    - test_network

Add a shell script at test_postman/run_newman.sh for Dockerized Newman to run the tests locally.

newman run SuperheroAPI.postman_collection.json -e Integration.postman_environment.json

And ensure it is executable:

chmod +x test_postman/run_newman.sh

We also need a version of the application’s configuration to run integration tests under config/integration.exs.

import Config

config :game_app, GameApp.Repo,
  username: "integration_user",
  password: "integration_password",
  hostname: "localhost",
  port: 5483,
  database: "game_db_integration",
  pool_size: 10

config :game_app, GameAppWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 4003],
  secret_key_base: "y/Y/z8ZvjzZwaWhm6KMnGDeVQ8oaAmLmxNkDHSgCRrIUzQ+Vtae6tO6kYOUthcCm",
  server: true

Finally, add the following Makefile commands to manage the integration testing environment and to run integration tests:

setup.integration:
  @echo "Getting deps for integration environment..."
  MIX_ENV=integration mix deps.get
  @echo "Creating database for integration environment..."
  MIX_ENV=integration mix ecto.create
  @echo "Running migrations for integration environment..."
  MIX_ENV=integration mix ecto.migrate

reset.integration:
  @echo "Resetting database for integration environment..."
  MIX_ENV=integration mix ecto.drop
  @echo "Recreating database for integration environment..."
  MIX_ENV=integration mix ecto.create
  @echo "Migrating database for integration environment..."
  MIX_ENV=integration mix ecto.migrate

serve.integration:
  @echo "Recompiling and running the integration server..."
  MIX_ENV=integration mix clean
  MIX_ENV=integration mix compile
  MIX_ENV=integration mix phx.server

test.integration:
  @echo "Running Newman tests..."
  @docker-compose run newman

Create Tests

To set up integration tests using Postman:

  1. Configure the Integration Environment:
    • Use the Postman UI to add a new environment specifically for integration testing.
    • Set the base_url parameter appropriately to point to your integration testing server.
  2. Export and Save the Environment Configuration:
    • Export the environment settings from Postman.
    • Save the exported environment configuration file to your project directory under test_postman/Integration.postman_environment.json.
    • View the configuration file.
  3. Develop and Extract the Collection:
    • Create a collection of integration tests within the Postman UI tailored to your application’s needs.
    • After setting up the tests, extract this collection and save it as test_postman/SuperheroAPI.postman_collection.json in your project directory.
    • View the collection file.
  4. Initialize and Serve the Application:

    • Prepare and launch the integration testing environment using the following commands:

      make up
make setup.integrations
make serve.integrations
  5. Run the Integration Tests:

    • Open a new terminal window to execute the integration tests:

      make test.integrations

Adopting the Postman ecosystem has associated costs, but it is a helpful tool for implementing Consumer-Driven Contract Testing (CDCT), offering valuable functionalities to enhance testing workflows.