Ensure WSDL-generated file parity with webservice.go

internal/core/sapsystem/sapcontrolapi/README.md

@@ -1,29 +1,55 @@
 # SAPControl web service
 
-The SAPControl web service is the most common interface to interact with SAP instances.
-It offers a WSDL schema defining all the possible operations.
+This package provides a Go client for the SAPControl web service, the standard interface for interacting with SAP instances. It offers a curated, hand-written subset of the full WSDL schema, focusing on the operations required by the agent.
 
-The [hooklift/gowsdl](https://github.com/hooklift/gowsdl) library was used to create the related golang code.
-Find the complete auto-generated code in [./_generated_wsdl.go].
+The complete, auto-generated Go code from the WSDL, created using the `hooklift/gowsdl` library, is stored in `_generated_wsdl.go`. This file serves as a reference for the parity tests.
 
-As using all the operations is not intended, a simplified version of it has been extracted.
+## WSDL Code Generation
 
-## Autogenerated code
+To regenerate the `_generated_wsdl.go` reference file from a running SAP instance, follow these steps. This is typically only needed when the upstream WSDL changes.
 
-Follow the next instructions to generate the code from the WSDL:
+**Prerequisites:**
 
-Given that the machine where the commands are executed has a SAP application instance running and is running under a SLES machine:
+* A running SAP application instance.
+* Go (version 1.23 or later) and Git installed.
 
-```
-# Install golang (at least 1.20 version) and git
+```console
+# Install required tools
 zypper in go1.23 git
+
 # Download [hooklift/gowsdl](https://github.com/hooklift/gowsdl)
 go install github.com/hooklift/gowsdl/cmd/gowsdl@latest
-# Generate the code. The `00` in `50013` is the value of the instance number of the SAP instance running in the machine
-~/go/bin/gowsdl -p sapcontrol -o _generated_wsdl.go http://localhost:50013/?wsdl
+
+# Generate the code from a running instance (e.g., instance 00)
+~/go/bin/gowsdl -p sapcontrolapi -o _generated_wsdl.go http://localhost:50013/?wsdl
+
 # Copy the code from sapcontrol/_generated_wsdl.go to your final destination
 ```
 
+## Testing
+
+* `webservice_test.go` runs each hand-written operation against a fake SOAP server and checks the response decodes correctly.
+* `parity_test.go`'s ensures `webservice.go`'s hand-written subset is in sync with the autogenerated `_generated_wsdl.go`. If new operations are added to the WSDL, this test will not fail, but it will log the new operations that are not yet wrapped in `webservice.go`.
+
+Run with:
+
+```sh
+go test ./internal/core/sapsystem/sapcontrolapi/...
+```
+
+To get the list of new operations, run the parity test with `-v`:
+
+```sh
+go test ./internal/core/sapsystem/sapcontrolapi/... -run TestFeatureParityWithGeneratedWSDL -v
+```
+
+### Adding a new operation
+
+1. Add the new method to the `WebService` interface in `webservice.go`.
+2. Implement the method on `webService` using the `CallContext` pattern from an existing method. Add the corresponding request, response, and any other required types to `webservice.go`, ensuring they match the structure in `_generated_wsdl.go`.
+3. Add a new test for the operation in `webservice_test.go`. Follow the existing test structure, which uses a fake SOAP server and canned responses.
+4. Run the tests. `TestFeatureParityWithGeneratedWSDL` will automatically validate the new operation's signature against the generated code, while your new test will verify the SOAP decoding.
+
 ## References
 
-- [How to user the SAPControl Web Service Interface](https://www.sap.com/documents/2016/09/0a40e60d-8b7c-0010-82c7-eda71af511fa.html)
+* [How to user the SAPControl Web Service Interface](https://www.sap.com/documents/2016/09/0a40e60d-8b7c-0010-82c7-eda71af511fa.html)