docs: add gamification bonus questions per step (Microcks focus)

Open
  • Is something wrong?
#5 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp, kafka, openapi, postman
Domain
documentation

Research direction

Review the existing stepN-*.md workshop files and the proposed questions, starting with the corresponding Step 1–5 sections. Select and integrate the appropriate English questions without the animator notes, then verify that wording and difficulty labels fit the existing workshop structure.

Written by the indexing model from the issue text.

Description

stale

Proposal

Add extra 🎁 Bonus step questions per step to bring a gamification dimension to the workshop, focused on Microcks. Questions follow the existing open-ended "How can you…?" bonus style and are tagged by difficulty: 🟢 easy / 🟡 medium / 🔴 expert.

Animator answer notes are provided in collapsible blocks — for facilitators only, not meant to be integrated verbatim into the step docs.

Step 1 — Getting Started

  • 🟢 Why is a single Microcks container enough to mock both the Pastry REST API and the Kafka events? What does it save compared to running one mock per dependency?
Animator note

Microcks is multi-protocol: one container imports both OpenAPI and AsyncAPI artifacts, serves REST mocks over HTTP and connects to the Kafka broker to publish/consume events. Avoids stacking WireMock + a Kafka mock + a fake review service: one source of truth (the contracts), one container to manage in tests.

Step 2 — Exploring the App

  • 🟢 OpenAPI vs AsyncAPI — why two contract types? Which one describes the Pastry API, which one the Order Events, and what can Microcks do with each?
  • 🟡 Mock vs contract-test — Microcks plays two different roles here. Which ones, and for which component (PastryApiClient vs OrderController)?
Animator note
  • OpenAPI → Pastry API (synchronous REST). AsyncAPI → Order Events (Kafka, event-driven). Microcks consumes both: generates mocks from examples and acts as a conformance tester.
  • Mock: for PastryApiClient, Microcks simulates the third-party dependency (we consume its mocks). Contract-testing: for the Order API, Microcks tests our exposed API by calling it with contract examples and validating responses. Consumer side → mock; provider side → verify.

Step 3 — Local Development (complements existing dispatcher bonus)

  • 🟢 Without Microcks, how many real services would you need to boot the app locally (Pastry API, review system, Kafka broker)? What does ./microcks.sh actually replace?
  • 🟡 "Eclair Chocolat unavailable" — where does this response come from? Find the matching example in the OpenAPI spec and explain how the dispatcher selects it.
  • 🔴 Multi-protocol — in the Microcks UI, find the Kafka mock for Order Events. How often does it republish, and where is that frequency defined?
Animator note
  • At least three: Pastry API, review system, Kafka broker. ./microcks.sh replaces all of them with one preloaded Microcks container → inner-loop starts with zero real deps.
  • It's an example in the Pastry OpenAPI spec (status: unavailable). The dispatcher (content/name-based) routes the request to the right example response.
  • Default 3 seconds, driven by AsyncAPI frequency extension in order-events-asyncapi.yaml.

Step 4 — REST Tests (complements Verify / TestResult / Postman bonuses)

  • 🟡 Spec reuse — the conformance test has no manual JSON assertions. Where are the validation rules actually defined, and what drift risk does this remove?
  • 🟡 host.testcontainers.internal — why not localhost in TestEndpoint? What does this alias represent from the Microcks container's point of view?
  • 🔴 Technical vs business — difference between the OPEN_API_SCHEMA and POSTMAN runners? Give a bug the first would miss but the second would catch.
  • 🔴 GetServiceInvocationsCountAsync +3 — why exactly 3 invocations? What would a mismatch reveal (cache, retry, missing call)?
Animator note
  • In the OpenAPI contract itself. No manual JSON assertions → removes double maintenance (spec + hand-written assertions) and the drift between the delivered spec and the tests.
  • Microcks (inside its container) calls our API. From inside the container localhost is the container itself; host.testcontainers.internal points to the host running the test app on its dynamic port.
  • OPEN_API_SCHEMA = technical/structural conformance (types, required fields, HTTP codes). POSTMAN = business conformance (products/quantities unchanged, total price correct…). Swapping the total price or losing a product stays structurally valid → schema passes, Postman fails.
  • The test calls 3 pastries (Millefeuille, Eclair Cafe, Eclair Chocolat) → 3 mock hits. A mismatch would signal a cache (fewer), a retry (more) or a missing call.

Step 5 — Async Tests (complements event-content / value-origin bonuses)

  • 🟡 Role inversion — in the publisher test, who listens and who emits? And in the consumer test? Explain why Microcks switches sides.
  • 🟡 Why 4 seconds of polling when Microcks publishes every 3s? What happens if the window drops below the publication frequency?
  • 🔴 AsyncAPI validation — when the publisher test goes green, what did Microcks actually validate on the Kafka message, beyond "a message arrived"?
  • 🟢 123-456-789 / lbroudoux — these values are nowhere in the test code. Where do they come from, and what does that prove about the test's source of truth?
Animator note
  • Publisher test: app emits on orders-created, Microcks listens and validates against AsyncAPI. Consumer test: Microcks publishes mock messages on orders-reviewed, app consumes. AsyncAPI describes both directions, so Microcks can play producer or verifier.
  • The window must exceed the publication frequency to reliably catch at least one message. Below 3s the test could expire before Microcks publishes → flaky false negative.
  • Not just "a message arrived": Microcks validates the Kafka message is AsyncAPI-conformant (structure, fields, types, JSON serialization) → Kafka config, JSON serializer and network are all correct.
  • They're examples in order-events-asyncapi.yaml (messages/examples). Microcks publishes them; the test expects them → the contract is the source of truth.

Gamification notes

  • Increasing difficulty per step: 1 warm-up 🟢 + 1 deepening/trap 🔴 per step.
  • "Guess the output" format: show a TestResult or an invocation count and have the room guess success/failure or the value — very visual.
  • Difficulty badges 🟢🟡🔴 to pace the session.

Scope

  • Validate wording
  • Integrate selected questions into stepN-*.md (EN, without animator notes)
Dominant language
C#
Stars
0
Forks
0
Avg merge
11m
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microcks/microcks-testcontainers-dotnet-workshop

All issues in microcks/microcks-testcontainers-dotnet-workshop

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.