Documentation too "chopped up" to get a clear idea how to use it.

[wolfch-elsevier]

Describe the issue There is a multi-step "getting started" trail here: https://www.mock-server.com/mock_server/getting_started.html but the problem is that each step has a multitude of ways for accomplishing each step - I am not critical of that approach, but if I follow the Java steps, it doesn't result in a successful example.

What you are trying to do I want to establish a local mock of my REST web service for testing the web service client code.

MockServer version Version 5.11.2

To Reproduce

@ExtendWith(MockServerExtension.class) // <=== JUnit5
@MockServerSettings(ports = {8686})
public class MyServiceClientTest {
  @Autowired
  private MyServiceClient myAPI;

  private final ClientAndServer client;

  public LookupServiceTest(ClientAndServer client) {
    this.client = client;
  }
[...]
}

The step of creating expectations was very confusing and incomplete. https://www.mock-server.com/mock_server/getting_started.html#setup_expectations This step shows only the bare minimal example of creating an instance of MockServerClient without any context, such as how/when/where that instance should be injected into the test. I have no clue and the documentation doesn't say how. Even just literally copy/pasting that code fragment into a method of the test class results in undefined method calls:

 void createDemoExpectation() {
    new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("POST")
            .withPath("/login")
            .withBody("{username: 'foo', password: 'bar'}")
    )
    .respond(
        response()
            .withStatusCode(302)
            .withCookie(
                "sessionId", "2By8LOhBmaW5nZXJwcmludCIlMDAzMW"
            )
            .withHeader(
                "Location", "https://www.mock-server.com"
            )
    );
  }

...the errors are that request() and response() are undefined, however none of the preceding steps in : https://www.mock-server.com/mock_server/getting_started.html mention how to define these methods.

I think having segmented, expandable "accordion" sections of the documentation is fine for reference when there are many approaches to using this library, but I think it would be extremely helpful to provide full, complete end-to-end examples that will actually run when copy/pasted into a local project.

Expected behavior I expected to be able to get the most basic Java/JUnit5 test to work.

MockServer Log Log output, as INFO level (or lower)

[wolfch-elsevier]

Hi, since I filed this ticket, I found by web search: https://github.com/mock-server/mockserver/tree/master/mockserver-examples ...that should most definitley be mentioned in "Getting Started". these explain some, but not all of my questions. For example, now I know request and response are static imports that Eclipse auto-suggest could not detect. Still a bit unsure how to implement an end-to-end basic web client test with mocked server responses,.

[ChristianLMI]

Came here with the same issue. Thanks @wolfch-elsevier for linking the examples. That will help me out. The most important information I'm missing is what to import for the static references to request() and response().

[earniedyke]

@ChristianLMI

request() and response() can be statically imported via:

import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;

[ChristianLMI]

Exactly... the point is that this is not in the docs. Where it IMHO definitely belongs.

I love static imports as they tend to make code more readable. But this is for code that has the imports. It's unfortunately a common thing to omit imports in snippets. While this does no harm in most places this is often not true for static imports.

[jamesdbloom]

I agree it could be clearer to provide the static imports or to not use staticly imported methods, I'll look into updating the documentation to that affect.

I also agree a clearer link to the examples repo from the getting starting pages would be helpful.