Improve documentation examples

[hubertlepicki]

I scanned through documentation again and I think we may be kind of giving misleading idea of how to use Mox in it.

Our first example is defining a mock, and then calls functions on the mock itself and verifies these were callled indeed.

https://github.com/plataformatec/mox/blob/master/lib/mox.ex#L43

While technically correct, I don't suppose anyone ever would want to write such code.

Instead, the real example of usage is that you define mocks in your tests, and switch the "backend" to to mocks in Mix.env() == :test using application configuration at compile time. The result is that in all environments you use some implementation module, while in tests you use mocks to provide "backend" functionality.

Most people will need to use mocks when they interact with external services. Most people, over HTTP.

I propose we update the documentation first example to be more of a "real world" use case. For example something along the lines of this blog post would do, I think:

https://medium.com/flatiron-labs/elixir-test-mocking-with-mox-b825a955143f

I have spoken with couple of people who mentioned the confusing documentation and I think I understand now what is wrong here. We just need a better, and more real-world example on how to use the library. @josevalim should I work on providing one?

[josevalim]

Actually, I like the calling the mock approach because if you can avoid the environment variable and pass the mock through other ways, then passing the mock will always be preferred. The application environment is necessary only when you are integration testing. So perhaps it could be a section dedicated to integration? Thank you for opening up the discussion.

[hubertlepicki]

I don't actually insist on the application environment. My main beef with our current examples is that you declare a mock, and then call functions on the mock you just defined.

I think you would never ever write a test code like that. You always define a mock, and then have something else calling it, indirectly.

I don't mind if we show that we are passing mock, to tested functions via environment or extra default function parameter or some other way like that. But you would never call functions on a mock in tests directly.

On Tue, Oct 8, 2019 at 12:22 PM José Valim notifications@github.com wrote:

Actually, I like the calling the mock approach because if you can avoid the environment variable and pass the mock through other ways, then passing the mock will always be preferred. The application environment is necessary only when you are integration testing. So perhaps it could be a section dedicated to integration? Thank you for opening up the discussion.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/plataformatec/mox/issues/82?email_source=notifications&email_token=AAAID6UBEDK23RQ377VBTZ3QNRNNPA5CNFSM4I6PS2D2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEATVY6A#issuecomment-539450488, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAID6TCYN6AAV43CBFMG53QNRNNPANCNFSM4I6PS2DQ .

-- Hubert Łępicki phone: +48 694 161 264 email/Google+: hubert.lepicki@amberbit.com Skype: hubert.lepicki

AmberBit Sp. z o. o. ul. Hetmańska 42 lok. 205 15-727 Białystok

AmberBit Sp. z o. o. jest wpisana do Rejestru Przedsiębiorców Krajowego Rejestru Sądowego prowadzonego przez Sąd Rejonowy w Białymstoku, XII Wydział Gospodarczy Krajowego Rejestru Sądowego. Kapitał zakładowy 20 000,00 zł opłacony w całości. EU VAT: PL5423228204, NIP: 5423228204, KRS: 0000439100, REGON: 200741641

[josevalim]

I see. Yes, let's update it then! :D Please PR?

[josevalim]

Ping!

[sgilson]

@hubertlepicki Do you mind if I make an attempt at improving the first example?

[josevalim]

Closing this. Please feel free to PR if you still believe this is worth it. :)