Skip to main content
This page explains the concept of profiles in WireMock. For practical instructions on creating and using profiles to manage environments, see Managing Environments. Profiles provide a mechanism for applying named configuration overrides to your mock API services. They allow you to maintain a single base configuration while selectively modifying specific aspects for different use cases, contexts, or runtime scenarios.

​
What are profiles?

A profile is a named configuration overlay that modifies specific aspects of your base WireMock configuration without duplicating the entire configuration structure. Each profile is stored in a separate file named wiremock-<profile-name>.yaml that sits alongside your base wiremock.yaml configuration. When you activate a profile using the --profile flag, its configuration merges with and overrides matching values in the base configuration. This overlay mechanism means you define only what changes, not what stays the same.

​
Why profiles exist

Mock API configurations often need to vary depending on context:
  • Different target URLs for recording (local, staging, production APIs)
  • Different port assignments to avoid conflicts
  • Different TLS certificates for security contexts
  • Different cloud API IDs for environment isolation
  • Different validation modes for testing vs. production use
Without profiles, managing these variations requires either maintaining completely separate configuration files (which leads to duplication and drift) or manually editing configurations when switching contexts (which is error-prone and doesn’t scale). Profiles solve this by treating configuration variance as explicit, minimal, named overrides. This makes the relationships between configurations clear and keeps common elements in one place.

​
How profiles work

​
Configuration overlay

When you specify a profile, WireMock reads both the base configuration and the profile configuration, then merges them. The profile values override any matching base values while inheriting everything else. For example, given this base configuration: 
services:
  invoicing-api:
    type: REST
    name: "Invoicing API"
    port: 8888
    cloud_id: prod123
    originals:
      default: https://api.example.com
And this wiremock-staging.yaml profile: 
services:
  invoicing-api:
    cloud_id: staging456
    originals:
      default: https://staging-api.example.com
Using --profile staging produces this effective configuration: 
services:
  invoicing-api:
    type: REST
    name: "Invoicing API"
    port: 8888
    cloud_id: staging456
    originals:
      default: https://staging-api.example.com
The profile changed only the cloud_id and the originals.default URL—everything else came from the base configuration.

​
Profile scope

Profiles can override specific service properties, but they maintain structural constraints:
  • The same services must exist in both base and profile configurations
  • Service structure (service keys/names) cannot change
  • The service type cannot be overridden
  • New services cannot be added via profiles
These constraints ensure that profiles remain true overrides rather than separate, divergent configurations.

​
Common profile use cases

Recording from different sources: Override the originals section to record from different target services—production APIs, staging APIs, or local instances—depending on your current task. Port conflict avoidance: Change port assignments when multiple developers or processes need to run mock services simultaneously on the same machine. Security context switching: Apply different TLS certificates or validation modes depending on whether you’re doing local development, integration testing, or simulating production-like behavior. API specification variants: Use different OpenAPI validation modes—none for exploratory development, soft for testing with warnings, hard for strict contract validation.

​
Profiles for managing environments

One of the most common uses of profiles is managing environment-specific configurations—development, staging, production, and other deployment contexts where the same logical services need different runtime characteristics.

​
Environment isolation with cloud APIs

When working with WireMock Cloud, different environments typically map to different mock API instances. A staging profile might override the cloud_id field to point to staging-specific mock APIs, while a production profile points to production mock APIs. This allows the same local configuration structure to sync with environment-appropriate cloud instances. For example: 
# wiremock.yaml (base configuration)
services:
  invoicing-api:
    type: REST
    name: "Invoicing API"
    cloud_id: prod123
    port: 8888

# wiremock-staging.yaml (staging profile)
services:
  invoicing-api:
    cloud_id: staging456
Using --profile staging targets the staging cloud API while preserving all other configuration.

​
Environment-specific recording sources

Recording often needs environment-specific source URLs. Development might record from localhost, staging from internal services, and production from live APIs: 
# wiremock.yaml
services:
  payment-api:
    originals:
      default: https://api.production.example.com

# wiremock-dev.yaml
services:
  payment-api:
    originals:
      default: http://localhost:3000

​
Learn more

For details on the profile file format and how profile overlays work, see the wiremock.yaml Reference. For instructions on using profiles to manage WireMock Cloud environments, see Managing Environments. For information on using profiles with Runner, see Serve Mode and Runner Environment Variables. For details on WireMock Runner’s architecture and capabilities, see WireMock Runner.