Improve documentation

[simonvane]

I am really enjoying using MbDotNet but as I get into more difficult cases I am having trouble with working out what to use in those cases. In particular I am having trouble with predicates e.g. what's the difference between a MatchesPredicate and an EqualsPredicate etc.

An example I'm trying to achieve is for the predicate to not match if a query string is added that is not expected.

Anything you could add to clarify would be much appreciated.

[mattherman]

Thanks for the feedback, I definitely agree that the documentation could be improved. I will try to find some time to add to it and perhaps re-organize it. Do you have any other suggestions for improvement?

Certain things, like the difference between the predicate types, I am expecting people to learn from the mountebank docs themselves. I was avoiding duplicating that documentation, but I could be more clear about the different predicate types being implementations of the predicates described here.

For your specific example, I would use an EqualsPredicate since you want an exact match on the query string parameters. I have created a gist with some sample code showing how to accomplish that. In that example, http://localhost:4545/books?page=3&limit=25 would match the predicate and return the result, but http://localhost:4545/books?page=1&limit=25 would not.

Let me know if that helps.

[simonvane]

Thanks a lot for your quick response.

I can see your reasoning for avoiding duplication the mountebank documentation. I really like your Usage Examples page. Perhaps link to the specific parts of the mountebank documentation to point out more detail (and to remind people this is a layer over mountebank rather the a new implementation).

It would be really nice to have some more examples of more complex predicate use e.g. and / or predicates. One example for each predicate type would be really helpful. It's so quick to get going by looking at those code examples. In particular, I had no idea how to use and / or predicates or what the purpose of HttpBooleanPredicateFields is.

The case I was trying to setup was for a predicate not to match if any query string was added. I wanted to ensure that query strings were not added erroneously as opposed to the query string being added incorrectly. I didn't manage to achieve it with predicates.

In the end I set recordRequests to true on the imposter and inspected the requests after the call to ensure there was no query string.. It would be good enhance the Retrieving Imposters section of Usage Example. Perhaps rename it to Recording Requests and Retrieving Imposters and show an example of setup and inspection. The mistake I was making was trying to inspect the imposter object I created in the setup rather than calling client.GetHttpImposter(port); after running the requests. Basically I couldn't find the requests because I was looking at HttpImposter rather than RetrievedHttpImposter.

Thanks for your help, I'll have a read of the mountebank predicate examples.

[mattherman]

Those are all really good examples of things to improve on. Thank you.

Apologies for misunderstanding what you were trying to achieve with your imposter. I think the predicate you would want to use is "exists", but unfortunately MbDotNet does not support that predicate type currently. Someone asked a similar question here and the answer was the same. My next attempt was to combine a "not" predicate with either "contains" or "matches", but I wasn't able to figure out how to get that to work with query string parameters. It may be worth more exploration though. For now, I think you will probably need to continue your strategy of inspecting the retrieved imposter.

I am going to leave this issue open, if you don't mind, as a reminder to myself to spend some more time on the docs. Thanks again for all the feedback.

[thecolour]

Hi, I'd really appreciate a usage example for the MountebankClient method CreateHttpsImposter(int? port = default(int?), string name = null, string key = null, string cert = null, bool mutualAuthRequired = false, bool recordRequests = false);

[mattherman]

HttpsImposter is pretty similar to HttpImposter. The only difference are the additional parameters involved when creating them that you noted above. Port is the only one that will have some sort of meaningful default if you omit it, which is a random port number. The others are all truly optional and correspond to the properties of HTTPS imposters described in the mountebank docs here.

[mattherman]

Just bumping this to let people know I am still planning on doing something to improve this.

As part of those improvements I'm also considering moving away from the Github wiki format and instead include the docs as part of the source. I like that approach since the docs themselves will be implicitly tied to specific releases rather than needing to maintain multiple wiki pages for each version, but I also think that may be confusing since I know a lot of users are on older versions.

If anyone has thoughts about this, let me know.

[jzabroski]

I like Statiq (ex Wyam). I am planning to move to it for FluentMigrator docs, over DocFX. While DocFX is "used by Microsoft", they use such a heavily customized version that saying they use DocFX is like saying Microsoft uses mscorlib.dll to write BizTalk.

[mattherman]

Once I move the docs into source, I'm considering hosting it via Github Pages as well. I think GitDocs would be a good choice.

[mattherman]

Or not...it looks like the repo for that project has been archived. I am guessing it is no longer maintained. I liked that it was able to generate the site from plain markdown files since I'd like the documentation to be readable from source in case the site is ever down. I'll need to find an alternative that does something similar.

[tparikka]

I noticed that the V2 Example Files page has a broken link at the end to DocumentationTests.cs that could be corrected.

[mattherman]

Fixed in all versions of the docs. Thanks for letting me know.

[mattherman]

I've rewritten the documentation for the project. See #125. Let me know if you have any feedback.