Feat: Microcks-CLI v2 - IDE (Vs code) Integration and Local Dev Loop Enhancement

[Harsh4902]

Reason/Context

• LFX Proposal

Description

The Microcks CLI (microcks-cli, written in Go) is a key part of Microcks' CI/CD story - it lets developers trigger contract tests and import artifacts from the command line and in GitHub Actions. This project goes into the developer experience layer. Today, developers must navigate to the Microcks web UI in a browser to see test results, check mock status, and diagnose import errors. There is no IDE integration, no offline validation mode, and no way to get mock results inline with the code being tested. This project builds three focused improvements that bring Microcks into the editor and the local dev loop: a VS Code extension, a local dry-run mode powered by Testcontainers, and an updated GitHub Actions output format that annotates PRs with per-operation pass/fail results.

Implementation ideas

No response

[mugiwaraluffy56]

Hi @lbroudoux, @yada, @Harsh4902 - i've been working through the repository in detail to ground my proposal in the actual code. Here's my analysis and implementation plan.

Codebase audit

After a thorough read of the repo, here are the exact integration points relevant to this project:

Test command (cmd/test.go):
The core flow (lines 48-197) POSTs to /api/tests, then polls GetTestResult() every 2 seconds with a fixed deadline. Output is plain fmt.Printf with no structured format or annotations. There's no --dry-run flag and no --format flag. Exit code 1 is set on test failure, which is already CI-friendly, but no per-operation annotation data is surfaced.

Microcks client (pkg/connectors/microcks_client.go):
GetTestResult() (line 383) returns a *TestResultSummary - i'll need to extend this struct (currently lines 58-69) to expose per-operation TestCaseResult data so github actions annotations can reference specific operation failures rather than just the top-level pass/fail.

Container management (cmd/start.go, pkg/connectors/container_client.go):
The CLI already wraps the docker SDK directly to CreateContainer / StartContainer. There is no testcontainers dependency and no container health-check / readiness wait. The --dry-run implementation will need to add github.com/testcontainers/testcontainers-go and the microcks module (github.com/microcks/microcks-testcontainers-go), then orchestrate: spin-up -> readiness check -> import -> test -> teardown - reusing the existing MicrocksClient interface against the ephemeral container's URL.

Config (pkg/config/localconfig.go):
The config file is always disk-backed. For --dry-run, the client will be constructed in-memory directly from flags, bypassing the config file entirely - same path already used in cmd/test.go lines 99-156 when --microcksURL / --keycloakClientId / --keycloakClientSecret are all provided.

Github actions (.github/workflows/build-verify.yml):
No annotation output today. The CI file has no use of ::error:: / ::notice:: workflow commands, and no GITHUB_STEP_SUMMARY writing.

Proposed implementation plan

1. microcks test --dry-run

Add a --dry-run bool flag to cmd/test.go. When set:

1. Pull quay.io/microcks/microcks-uber:latest via testcontainers-go with a Wait.ForHTTP("/api/health") readiness strategy - solves the current gap where start.go doesn't wait for container readiness.
2. Construct an in-memory MicrocksClient pointed at the ephemeral container's mapped port.
3. Import the specified artifact via mc.UploadArtifact().
4. Run the normal CreateTestResult -> poll loop - existing logic unchanged.
5. Print results, then call container.Terminate(ctx).

The --dry-run path requires no microcks server and no keycloak credentials; the uber image ships with auth disabled.

2. Github actions output format

Add --format flag to cmd/test.go with values text (default, current behavior) and github-actions.

In github-actions mode:

• Write ::error title=Test Failed::<serviceID> - operation <opName> failed for each failed TestCaseResult, mapped back to the spec file using the filteredOperations metadata.
• Write a GITHUB_STEP_SUMMARY markdown table summarising per-operation pass/fail, elapsed time, and a direct link to the full result in the microcks UI.
• This requires extending TestResultSummary to deserialize testCaseResults from the /api/tests/{id} response.

3. VS code extension (microcks-vscode)

The extension will talk to a configured microcks instance over its REST API - same endpoints the CLI already uses:

• Services view: GET /api/services to list loaded mocks with status.
• Test results panel: GET /api/tests?serviceId=... to show recent runs inline.
• Import trigger: shell-exec the CLI's import command from the editor, then refresh the services view.
• Configuration: stored in VS code workspace settings, mirroring the ~/.microcks-cli/config.yaml context model.

The extension will be written in TypeScript using the VS code TreeView and WebviewPanel APIs, similar to the thunder client layout mentioned in the issue.

About me

I'm a go and TypeScript developer with experience building CLI tools, VS code extensions, and working with container-based test infrastructure. I've read through the full source - cmd/, pkg/connectors/, pkg/config/ - and i'm confident i can deliver all three deliverables within the LFX timeline. Happy to discuss any of the design choices above or adjust scope based on mentor feedback.

[hiranya25]

Description: The Microcks CLI (microcks-cli, written in Go) is a key part of Microcks' CI/CD story - it lets developers trigger contract tests and import artifacts from the command line and in GitHub Actions. This project goes into the developer experience layer. Today, developers must navigate to the Microcks web UI in a browser to see test results, check mock status, and diagnose import errors. There is no IDE integration, no offline validation mode, and no way to get mock results inline with the code being tested. This project builds three focused improvements that bring Microcks into the editor and the local dev loop: a VS Code extension, a local dry-run mode powered by Testcontainers, and an updated GitHub Actions output format that annotates PRs with per-operation pass/fail results.
Expected Outcome:
A VS Code extension (microcks-vscode) published to the VS Code Marketplace that connects to a running Microcks instance and shows: loaded services, mock operation status, recent test run results, and importer job logs - all inline in the editor sidebar (Like postman, thunder client)
A microcks test --dry-run flag in the CLI that uses Testcontainers (the Microcks uber image) to spin up an ephemeral local Microcks instance, import the specified artifact, run the contract test, report results, and tear down - with no external Microcks server required
A demo video and documentation page on microcks.io showing the full local-to-CI workflow

[yuvraj-kolkar17]

Hello @Harsh4902 ,
I am writing to express my interest in the Microcks CLI v2 – IDE (VS Code) Integration and Local Dev Loop Enhancement project for LFX Mentorship 2026 Term 2.
I am drawn to this project because of its clear, focused goals building a VS Code extension, adding a dry-run mode, and improving GitHub Actions output. I believe these deliverables will have a real impact on developer experience.

I have experience with Go and TypeScript, and I am familiar with Docker and CLI tooling also i have the experince with CNCF projects

[Caesarsage]

Microcks CLI v2 — IDE Integration & Local Dev Loop

Hi @lbroudoux, @yada, @Harsh4902 — putting my hat in the ring for this issue. I've contributed to microcks-cli#172 and microcks#1968, plus docs work on microcks.io, and I'm on the community calls fairly regularly. I'm also an active Kubernetes contributor, so the CNCF / multi-repo PR workflow isn't new to me. I read through the CLI at HEAD before writing this rather than pitching from the issue description alone.

What I found reading the code

The test command in cmd/test.go does a linear flow: build a Microcks client, fetch the Keycloak URL, get a token if needed, CreateTestResult, then poll GetTestResult every 2 seconds (test.go#L151-L167). The Keycloak flags are marked required (test.go#L190-L192) — fine for the current flow but blocks any dry-run path that doesn't need auth, so that constraint has to come off conditionally.

TestResultSummary (microcks_client.go#L59-L69) only deserializes top-level pass/fail. The /api/tests/{id} response actually carries a testCaseResults[] array with per-operation outcomes that gets thrown away today — that's the data the GitHub Actions annotations need.

cmd/start.go wraps the docker/podman SDK directly (both supported via start.go#L151) but has no readiness wait after StartContainer — the kind of race users hit and don't quite understand.

The piece I think the current discussion is missing: microcks-testcontainers-go already exists as a sibling repo, with RunContainer, ImportAsMainArtifact, TestEndpoint, and the right wait.ForLog("Started MicrocksApplication") strategy. The CLI should depend on it rather than re-wire testcontainers from scratch. Two implementations of "spin up a Microcks container" would drift, and the testcontainers-go module is the one already tested across versions of the uber image.

build-verify.yml has zero workflow-command output today, so the GitHub Actions piece is greenfield.

1. microcks test --dry-run

Add microcks-testcontainers-go to go.mod. Add a --dry-run bool to the test command, and make the three Keycloak flags optional when it's set (manual validation in the cobra Run func, since MarkFlagRequired is static).

The dry-run path itself is short:

• microcks.Run(ctx, ...) to start the uber-native image
• resolve HttpEndpoint(ctx) and build a MicrocksClient against it
• import the artifact, then run the existing CreateTestResult + poll loop unchanged
• defer container.Terminate(ctx) wired into a signal.NotifyContext so Ctrl-C still tears down

Keeping the existing poll loop untouched is deliberate — every divergence is a place for behavior to drift.

A new flag is needed: --artifact <path>. The current test command takes a serviceRef like Pastry API:1.0.0 and assumes the artifact is already loaded; for dry-run there's no preloaded server, so it needs a file.

Things I'm planning around:

• Cold CI image pulls. The uber image is large. Document Docker layer caching for GH Actions and let users override the image tag.
• Docker vs podman. testcontainers-go's podman story is rough across platforms. Ship dry-run as Docker-only at first and call that out clearly.
• Image flavor. uber-native ships with auth disabled; the regular uber image doesn't. Default to native and refuse non-native with a real error.

2. --format github-actions

The interesting part isn't ::error:: — it's ::error file=,line=::. Mapping a failed operation back to its location in the OpenAPI/AsyncAPI file turns the failure into a PR-inline annotation on the diff. That's the real UX win. Mapping is best-effort for OpenAPI (parse with getkin/kin-openapi); GraphQL/AsyncAPI start with whole-file annotation and improve from there.

Beyond that:

• ::group:: / ::endgroup:: to fold per-operation logs — services with 50+ operations otherwise turn the run log into a wall.
• A markdown table written to GITHUB_STEP_SUMMARY for the PR Summary tab, only when the env var is set.
• Existing exit codes preserved (test.go#L172) so if: failure() steps still fire.

I'd add --format json alongside, since once the reporter is abstracted into a pkg/output/ package the marginal cost is small and it makes the CLI usable from non-GitHub CI. SARIF is a stretch — independently valuable for Code Scanning, only worth doing if the main format work lands cleanly.

TestResultSummary grows additively to deserialize testCaseResults[] — backward compatible.

3. VS Code extension

Scaffolded with yo code, TypeScript, packaged as a .vsix.

The thing easy to get wrong: config source of truth. The CLI already reads ~/.microcks-cli/config.yaml with multi-context support. The extension should read the same file rather than introducing a parallel config in workspace settings. Workspace settings can override but shouldn't replace.

Sidebar tree views — Services, Recent tests, Importer jobs — all backed by the existing REST API. For v1, "click a test result" opens the Microcks UI in a browser rather than rebuilding that view inside the extension. Result rendering is a rabbit hole and not where the user value is.

Commands: import current file, run dry-run for current spec (this is where (1) pays off — same code path), switch context.

Auth: detect Keycloak via GET /api/keycloak/config, store credentials in vscode.SecretStorage (never settings.json), refresh tokens on 401.

Resilience: cache the last successful services list, show stale-with-banner when offline.

Marketplace publishing has a multi-day onboarding for a new publisher under an org, so the publisher PR on the Microcks side wants to go up early, not at the end.

Stretch goal — code lens on OpenAPI files. Inline "Run mock test" and "View last result" actions above each path/operation. Cheap to add once the services tree view is wired up; defer if core scope runs long.

4. Demo and docs

Short screencast covering the full loop — write a spec, import via VS Code, dry-run, push PR, see annotations — plus a docs page on microcks.io and a sample repo with a working GitHub Actions workflow.

One open question for mentors

Whether the extension lives in a fresh microcks-vscode repo or somewhere existing. That decision changes the early setup (publisher namespace, CI, branch protection) and I'd rather settle it on the first call than guess.