feat(core)!: New behaviour of using contacts like snapshots - the new setting changedContracts changes the behaviour when contracts are changed. Either 'FAIL' for fail when a contract is changed, or 'OVERWRITE' for overwriting when a contract is changed. Default is to FAIL, so this is a breaking change.

Author: TimothyJones

docs/maintainers/AddiingConfigurationOptions.md

@@ -0,0 +1,55 @@
+# How to add a new configuration option
+
+Follow this guide when you want to add a new configuration option to configure the core behaviour of ContractCase.
+
+## Design
+
+ContractCase can take configuration options that change the core behaviour of the matching engine, test runner, contract writing, and broker configuration (etc).
+
+### Ultimately, configuration is context
+
+The configuration itself isn't passed around, instead it becomes properties on
+the context object (RunContext) that tells ContractCase how it is running.
+
+This flattening into one object allows ContractCase to be agnostic to how it was
+configured, and consistent about precedence of configuration methods.
+
+Note that configuration should be in the `_case:currentRun:context:` namespace and not the `_case:context:` namespace. This is because `_case:context:` properties are able to be overwritten by matchers - which generally isn't desirable for configuration.
+
+### Context should generally be facts
+
+Ideally, it's best if ContractCase can check one value in the configuration to determine how one setting should behave, instead of needing to check multiple different values.
+
+This means that you may want to add a composite property to the context instead of a property that's the same as the configuration setting.
+
+### Defaults should be explicit, and applied before the context is created
+
+Don't spread defaults throughout the code.
+
+### Note: The configuration options described here aren't for interaction behaviour
+
+If you're wanting to configure a particular interaction type, then instead refer
+to the interaction plugin definitions (eg MockConfig).
+
+## Step 1: Add to Core
+
+The core needs to know your configuration property
+
+1. Add your property to the core's `CaseConfig` (usually `BaseCaseConfig`).
+   If your property is required for ContractCase to operate, then make it required here (even if users aren't expected to specify it)
+2. Add the option to the `RunContext` type. This is made of a few different sub-contexts, for use by parts of the ecosystem that don't have access to the full config object. It may be appropriate to add it to one of the sub-contexts instead of directly. Note that you might want to add a composite property here instead.
+3. Ensure the value is mapped between `CaseConfig` and `RunContext` appropriately. For most configuration properties, the method `configToRunContext` is sufficient and doesn't need to be modified.
+4. If your config has default values, add them to DEFAULT_CONFIG / dependencies.ts as appropriate
+
+## Step 2: Add to the CaseConnector packages
+
+1. Add it to `ContractCaseBoundaryConfig`. This should only contain primitive types, so that different connector implementations are possible. Keep this defined in the same order as the CaseConfig object. This object should be documented, and should specify what the default is.
+2. Add it to the `convertConfig` function. This function should validate the values can be assigned to the typescript CaseConfig, but do no other validation. It may also normalise if the result is unambiguous (eg, you can interpret `someProperty` as `SOME_PROPERTY`)
+3. Add it to the `.proto` version of the config object in `case-connector-proto`, then run `npm run build:proto` and `npm run lint:fix:proto=` in that package.
+4. Add it to `ContractCaseConnectorConfig`, using the same rules as the boundary config. TODO: Replace the boundary config with the connector config so that we only have to do one mapping here.
+5. Add it to `mapAllConfigFields` in the grpc connector
+
+## Step 3: Add it to the DSL packages
+
+1. For JS, this is `ContractCaseConfig` and the associated mapper to `ContractCaseBoundaryConfig`
+2. For Java, this is `ContractCaseConfig`, `IndividualFailedTestConfig`, `IndividualSuccessTestConfig`, `ContractCaseConnectorConfig`, and their associated builders. You will also need to add mappers in `ConnectorConfigMapper` and `ConnectorOutgoingMapper`.

docs/maintainers/todo.md

@@ -43,6 +43,10 @@ Next:
 - [ ] Do a configuration error message like the crash message, so that misconfigurations don't result in stack traces
 - [ ] Ensure original stack traces are maintained across boundaries and implement `originalStack` function.
 - [ ] Add way to say 'I need this field and I don't care what's in it'
+- [ ] Replace direct access of context in the core with selector methods, so that the logic is consistent and will read more fluently
+- [ ] Validate config - some settings can come as arbitrary strings (eg from env), and we could be more helpful if there are errors
+- [ ] Allow both `CASE_foo` and `CASE_FOO` environment variables (but fail if they're both set to different things).
+- [ ] Make sure that downloaded contracts don't write to `main`, and don't collide with local contracts.
 
 Document
 

packages/case-connector-proto/proto/contract_case_stream.proto

@@ -37,11 +37,12 @@ message ContractCaseConfig {
   map<string, string> mock_config = 16;
 
   google.protobuf.StringValue auto_version_from = 17;
+
+  google.protobuf.StringValue changed_contracts = 18;
 }
 
 // Indicates a successful response with no payload
-message ResultSuccess {
-}
+message ResultSuccess {}
 message ResultSuccessHasMapPayload {
   // Always a map of Strings -> Strings
   google.protobuf.Struct map = 1;
@@ -77,9 +78,7 @@ message StateHandlerHandle {
 }
 
 // A reference to a trigger function that can be invoked
-message TriggerFunctionHandle {
-  google.protobuf.StringValue handle = 1;
-}
+message TriggerFunctionHandle { google.protobuf.StringValue handle = 1; }
 
 // Requests from client / host
 
@@ -105,14 +104,11 @@ message RunRejectingInteractionRequest {
 
 // From host to core, instructs the core to strip the matchers from a given
 // matcher / data object
-message StripMatchersRequest {
-  google.protobuf.Struct matcher_or_data = 2;
-}
+message StripMatchersRequest { google.protobuf.Struct matcher_or_data = 2; }
 
 // From host to core, instructs the core to finish the current contract
 // definition
-message EndDefinitionRequest {
-}
+message EndDefinitionRequest {}
 
 // From host to core, instructs the core to load a plugin
 message LoadPluginRequest {
@@ -124,9 +120,7 @@ message LoadPluginRequest {
 // Responses from server
 
 // From Core to Host, instructs the host to run a given state handler
-message RunStateHandlerRequest {
-  StateHandlerHandle state_handler_handle = 1;
-}
+message RunStateHandlerRequest { StateHandlerHandle state_handler_handle = 1; }
 
 // From Core to Host, requests the host invoke one of the user-provided
 // triggers.
@@ -139,9 +133,7 @@ message TriggerFunctionRequest {
   SetupInfo setup = 3;
 }
 
-message CoreFunctionHandle {
-  google.protobuf.StringValue handle = 1;
-}
+message CoreFunctionHandle { google.protobuf.StringValue handle = 1; }
 
 // Describes the setup of the currently executing Interaction
 message SetupInfo {
@@ -288,9 +280,7 @@ message PrintTestTitleRequest {
 //
 // Most messages must be acknowledged with a response - this indicates the
 // return of the previous message.
-message ResultResponse {
-  BoundaryResult result = 1;
-}
+message ResultResponse { BoundaryResult result = 1; }
 
 // From the Host to the Core, requests that a verification session begins
 message BeginVerificationRequest {
@@ -301,8 +291,7 @@ message BeginVerificationRequest {
 }
 
 // From the Host to the Core, requests a list of the available contracts
-message AvailableContractDefinitions {
-}
+message AvailableContractDefinitions {}
 
 // From the Host to the Core, instructs the core that the current verification
 // session is now configured, and asks it to execute the verification.

packages/case-connector-proto/src/grpc/proto/contract_case_stream_pb.d.ts

@@ -118,6 +118,13 @@ export class ContractCaseConfig extends jspb.Message {
     value?: google_protobuf_wrappers_pb.StringValue,
   ): ContractCaseConfig;
 
+  hasChangedContracts(): boolean;
+  clearChangedContracts(): void;
+  getChangedContracts(): google_protobuf_wrappers_pb.StringValue | undefined;
+  setChangedContracts(
+    value?: google_protobuf_wrappers_pb.StringValue,
+  ): ContractCaseConfig;
+
   serializeBinary(): Uint8Array;
   toObject(includeInstance?: boolean): ContractCaseConfig.AsObject;
   static toObject(
@@ -160,6 +167,7 @@ export namespace ContractCaseConfig {
 
     mockConfigMap: Array<[string, string]>;
     autoVersionFrom?: google_protobuf_wrappers_pb.StringValue.AsObject;
+    changedContracts?: google_protobuf_wrappers_pb.StringValue.AsObject;
   };
 
   export class UsernamePassword extends jspb.Message {

packages/case-connector-proto/src/grpc/proto/contract_case_stream_pb.js

@@ -834,7 +834,8 @@ proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.toObject = functi
     triggerAndTest: (f = msg.getTriggerAndTest()) && proto.io.contract_testing.contractcase.grpc.TriggerFunctionHandle.toObject(includeInstance, f),
     baseUrlUnderTest: (f = msg.getBaseUrlUnderTest()) && google_protobuf_wrappers_pb.StringValue.toObject(includeInstance, f),
     mockConfigMap: (f = msg.getMockConfigMap()) ? f.toObject(includeInstance, undefined) : [],
-    autoVersionFrom: (f = msg.getAutoVersionFrom()) && google_protobuf_wrappers_pb.StringValue.toObject(includeInstance, f)
+    autoVersionFrom: (f = msg.getAutoVersionFrom()) && google_protobuf_wrappers_pb.StringValue.toObject(includeInstance, f),
+    changedContracts: (f = msg.getChangedContracts()) && google_protobuf_wrappers_pb.StringValue.toObject(includeInstance, f)
   };
 
   if (includeInstance) {
@@ -958,6 +959,11 @@ proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.deserializeBinary
       reader.readMessage(value,google_protobuf_wrappers_pb.StringValue.deserializeBinaryFromReader);
       msg.setAutoVersionFrom(value);
       break;
+    case 18:
+      var value = new google_protobuf_wrappers_pb.StringValue;
+      reader.readMessage(value,google_protobuf_wrappers_pb.StringValue.deserializeBinaryFromReader);
+      msg.setChangedContracts(value);
+      break;
     default:
       reader.skipField();
       break;
@@ -1115,6 +1121,14 @@ proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.serializeBinaryTo
       google_protobuf_wrappers_pb.StringValue.serializeBinaryToWriter
     );
   }
+  f = message.getChangedContracts();
+  if (f != null) {
+    writer.writeMessage(
+      18,
+      f,
+      google_protobuf_wrappers_pb.StringValue.serializeBinaryToWriter
+    );
+  }
 };
 
 
@@ -1920,6 +1934,43 @@ proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.prototype.hasAuto
 };
 
 
+/**
+ * optional google.protobuf.StringValue changed_contracts = 18;
+ * @return {?proto.google.protobuf.StringValue}
+ */
+proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.prototype.getChangedContracts = function() {
+  return /** @type{?proto.google.protobuf.StringValue} */ (
+    jspb.Message.getWrapperField(this, google_protobuf_wrappers_pb.StringValue, 18));
+};
+
+
+/**
+ * @param {?proto.google.protobuf.StringValue|undefined} value
+ * @return {!proto.io.contract_testing.contractcase.grpc.ContractCaseConfig} returns this
+*/
+proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.prototype.setChangedContracts = function(value) {
+  return jspb.Message.setWrapperField(this, 18, value);
+};
+
+
+/**
+ * Clears the message field making it undefined.
+ * @return {!proto.io.contract_testing.contractcase.grpc.ContractCaseConfig} returns this
+ */
+proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.prototype.clearChangedContracts = function() {
+  return this.setChangedContracts(undefined);
+};
+
+
+/**
+ * Returns whether this field is set.
+ * @return {boolean}
+ */
+proto.io.contract_testing.contractcase.grpc.ContractCaseConfig.prototype.hasChangedContracts = function() {
+  return jspb.Message.getField(this, 18) != null;
+};
+
+
 
 
 

packages/case-connector/src/connectors/case-boundary/internals/boundary/config.types.ts

@@ -20,7 +20,7 @@ export interface UserNamePassword {
 /**
  * Configure a ContractCase run. See the [configuration documentation](https://case.contract-testing.io/docs/reference/configuring) for more details.
  *
- * Note that many of these types are more permissive than the reality - for
+ * Implementation note: many of these types are more permissive than the reality - for
  * example, the constrained string types are listed here as `string`, whereas
  * the core will only accept a limited number of values (eg, log level accepts
  * `'warn'` `'error'` etc, but not `'gibbons'`). Callers may rely on the
@@ -70,6 +70,17 @@ export interface ContractCaseBoundaryConfig {
    */
   readonly contractFilename?: string;
 
+  /**
+   * What to do if contracts have changed?
+   *
+   * - `"OVERWRITE"`: Replace the previous contract file
+   * - `"FAIL"`: Fail if attempting to write a contract that's different
+   *   to the previous one
+   *
+   * Default: 'FAIL'
+   */
+  changedContracts?: string;
+
   /**
    * Unique ID for this segment of the test run - it must be unique within a
    * run, but need not be unique between test runs. This is an internal

packages/case-connector/src/connectors/case-boundary/internals/mappers/config.ts

@@ -57,6 +57,22 @@ const mapAutoVersionFrom = (autoVersionFrom: string): 'TAG' | 'GIT_SHA' => {
   }
 };
 
+const mapChangedContracts = (
+  changedContracts: string,
+): 'FAIL' | 'OVERWRITE' => {
+  switch (changedContracts.toUpperCase()) {
+    case 'FAIL': {
+      return 'FAIL';
+    }
+    case 'OVERWRITE':
+      return 'OVERWRITE';
+    default:
+      throw new CaseConfigurationError(
+        `The changedContracts setting '${changedContracts}' is not a valid changed contracts setting`,
+      );
+  }
+};
+
 /**
  * SeparateConfig only exists because at one point these two things were separate.
  * At some point, we should refactor this so that the config shape doesn't need to
@@ -67,20 +83,37 @@ type SeparateConfig = {
   partialInvoker: Partial<TestInvoker<AnyMockDescriptorType, unknown>>;
 };
 
+/**
+ * Converts between the boundary config (which is less restricted) and a
+ * validated form of CaseConfig.
+ *
+ * Here, validated means "conforms to the typescript definition of CaseConfig".
+ *
+ * Mappers should throw `CaseConfigurationError` if the values in the boundary config
+ * can't be assigned to the CaseConfig.
+ *
+ * @internal
+ * @param param0 - A boundary config object
+ * @returns a validated case config object
+ */
 export const convertConfig = ({
   stateHandlers,
   triggerAndTest,
   triggerAndTests,
   logLevel,
   publish,
   autoVersionFrom,
+  changedContracts,
   ...incoming
 }: ContractCaseBoundaryConfig): SeparateConfig => ({
   config: {
     ...incoming,
     ...(autoVersionFrom
       ? { autoVersionFrom: mapAutoVersionFrom(autoVersionFrom) }
       : {}),
+    ...(changedContracts
+      ? { changedContracts: mapChangedContracts(changedContracts) }
+      : {}),
     ...(logLevel ? { logLevel: mapLogLevel(logLevel) } : {}),
     ...(publish ? { publish: mapPublish(publish) } : {}),
     // baseUrlUnderTest: `http://localhost:${8084}`,

packages/case-connector/src/connectors/grpc/requestMappers/config/config.ts

@@ -135,6 +135,7 @@ const mapAllConfigFields = (
   logLevel: unboxOrUndefined(config.getLogLevel()),
   contractDir: unboxOrUndefined(config.getContractDir()),
   contractFilename: unboxOrUndefined(config.getContractFilename()),
+  changedContracts: unboxOrUndefined(config.getChangedContracts()),
 
   publish: unboxOrUndefined(config.getPublish()),
   brokerCiAccessToken: unboxOrUndefined(config.getBrokerCiAccessToken()),

packages/case-connector/src/domain/types.ts

@@ -6,12 +6,16 @@ export type ConnectorStateHandler = BoundaryStateHandler;
 
 export type ConnectorTriggerFunction = ITriggerFunction;
 
+// TODO: This should be consolidated with the boundary
+// config types so that there's only one mapping layer here
+
 export type ContractCaseConnectorConfig = {
   providerName: string;
   consumerName: string;
   logLevel: string;
   contractDir: string;
   contractFilename: string;
+  changedContracts: string;
 
   publish: string;
   brokerCiAccessToken: string;