#|
#|  Copyright The Telepact Authors
#|
#|  Licensed under the Apache License, Version 2.0 (the "License");
#|  you may not use this file except in compliance with the License.
#|  You may obtain a copy of the License at
#|
#|  https://www.apache.org/licenses/LICENSE-2.0
#|
#|  Unless required by applicable law or agreed to in writing, software
#|  distributed under the License is distributed on an "AS IS" BASIS,
#|  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#|  See the License for the specific language governing permissions and
#|  limitations under the License.
#|

- ///: |
    `_ext.Stub_` is the mock stub object consumed by `fn.createStub_`. It
    contains exactly one non-internal `fn.*` matcher plus a matching `->`
    result payload that the mock should return.

    See https://raw.githubusercontent.com/Telepact/telepact/main/doc/02-design-apis/05-mock-extensions.md
    for full `_ext.Stub_` rules and end-to-end examples.
  _ext.Stub_: {}

- ///: |
    `_ext.Call_` is the mock call object used by `fn.verify_` and verification
    failures. It contains exactly one non-internal `fn.*` key whose value is
    that function's argument object.

    See https://raw.githubusercontent.com/Telepact/telepact/main/doc/02-design-apis/05-mock-extensions.md
    for full `_ext.Call_` rules and end-to-end examples.
  _ext.Call_: {}

- ///: The number of times a function is allowed to be called.
  union.CallCountCriteria_:
    - Exact:
        times: "integer"
    - AtMost:
        times: "integer"
    - AtLeast:
        times: "integer"

- ///: Possible causes for a mock verification to fail.
  union.VerificationFailure_:
    - TooFewMatchingCalls:
        wanted: "union.CallCountCriteria_"
        found: "integer"
        allCalls: ["_ext.Call_"]
    - TooManyMatchingCalls:
        wanted: "union.CallCountCriteria_"
        found: "integer"
        allCalls: ["_ext.Call_"]

- ///: |
    Create a mock stub from an `_ext.Stub_`.

    By default the stub matcher is partial, so extra fields on the actual
    request argument are allowed. Set `strictMatch!` to `true` to require exact
    argument equality instead.

    Set `count!` to limit how many matching calls consume this stub before it
    stops matching.
  fn.createStub_:
    stub: "_ext.Stub_"
    strictMatch!: "boolean"
    count!: "integer"
  ->:
    - Ok_: {}
  _errors: '^errors\.Validation_$'

- ///: |
    Verify that the mock received a call matching the given `_ext.Call_`.

    By default verification is partial and succeeds if at least one recorded
    call contains the given argument as a JSON sub-structure. Set
    `strictMatch!` to `true` to require exact argument equality.

    Set `count!` to require `Exact`, `AtLeast`, or `AtMost` matching call
    counts. Matching calls are marked as verified, which affects
    `fn.verifyNoMoreInteractions_`.
  fn.verify_:
    call: "_ext.Call_"
    strictMatch!: "boolean"
    count!: "union.CallCountCriteria_"
  ->:
    - Ok_: {}
    - ErrorVerificationFailure:
        reason: "union.VerificationFailure_"
  _errors: '^errors\.Validation_$'

- ///: |
    Verify that no interactions have occurred with this mock or that all
    interactions have been verified.
  fn.verifyNoMoreInteractions_: {}
  ->:
    - Ok_: {}
    - ErrorVerificationFailure:
        additionalUnverifiedCalls: ["_ext.Call_"]
  _errors: '^errors\.Validation_$'

- ///: Clear all stub conditions.
  fn.clearStubs_: {}
  ->:
    - Ok_: {}
  _errors: '^errors\.Validation_$'

- ///: Clear all call data.
  fn.clearCalls_: {}
  ->:
    - Ok_: {}
  _errors: '^errors\.Validation_$'

- ///: Set the seed of the random generator.
  fn.setRandomSeed_:
    seed: "integer"
  ->:
    - Ok_: {}
  _errors: '^errors\.Validation_$'

- errors.Mock_:
    - ///: |
        The mock could not return a result due to no matching stub being
        available.
      ErrorNoMatchingStub_: {}