Testing in the tutorial #934

butla · 2016-10-27T21:59:24Z

This aims to solve #253.
It's currently a work in progress.

@kgriffs Do you think I'm going in the right way with incorporating TDD into the tutorial?
Doesn't it break the flow or tone too much?
Also, do you have some deadline for the tutorial? Because I probably won't be able to work on it for a week now.

codecov-io · 2016-11-06T13:56:15Z

Codecov Report

Merging #934 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #934   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          31     31           
  Lines        2107   2031   -76     
  Branches      338    328   -10     
=====================================
- Hits         2107   2031   -76

Impacted Files	Coverage Δ
falcon/api.py	`100% <0%> (ø)`	✅
falcon/util/misc.py	`100% <0%> (ø)`	✅
falcon/api_helpers.py	`100% <0%> (ø)`	✅
falcon/errors.py	`100% <0%> (ø)`	✅
falcon/testing/client.py	`100% <0%> (ø)`	✅
falcon/request.py	`100% <0%> (ø)`	✅
falcon/response.py	`100% <0%> (ø)`	✅
falcon/routing/compiled.py	`100% <0%> (ø)`	✅

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d43d295...c5a8f4c. Read the comment docs.

butla · 2016-11-08T18:11:20Z

Pep8 checks for import order on my example files are failing. I can make them pass, but the order they require is bizarre (from examples/look/tests/test_app.py):

from unittest.mock import call, mock_open # standard library

from look.app import api # my own module

import msgpack # third party code
import pytest # still third party, in alphabetical order
import falcon # third party in reverse alphabetical order?
from falcon import testing

As I understand, PEP8 encourages standard/third-party/own (and alphabetical order in each section) import order.
Can someone offer some insight?

butla · 2016-11-09T16:25:10Z

@kgriffs Ok, I think I'm done. That's a big chunk of docs there... Hope you like it.

But I still have the problem with pep8 mentioned above.

Oh, and I've pointed to my own library in the section about functional tests, is that ok?

butla · 2016-11-30T19:46:09Z

@kgriffs Any update?

kgriffs

Really, this is an impressive tutorial, and will be a super helpful addition to the docs. Thank you! I added a number of suggestions inline, but most of them are fairly nitpicky. Thanks again!

kgriffs · 2017-01-17T22:08:55Z

docs/user/tutorial.rst

-    powered REPL that is good to have in your toolbox when
-    exploring a new library.
+    `bpython <http://bpython-interpreter.org/>`_ or
+    `ptpython <https://github.com/jonathanslenders/ptpython>`_ are another


Nitpick: "are another" ==> "are other"

kgriffs · 2017-01-17T22:14:11Z

docs/user/tutorial.rst

@@ -144,6 +164,8 @@ and add the following to it:

        def on_get(self, req, resp):
            resp.body = '{"message": "Hello world!"}'
+            # This line can be ommited, because 200 is the default code falcon


kgriffs · 2017-01-17T22:14:56Z

docs/user/tutorial.rst


 Gunicorn has still limitation that is not working on Windows. If you are Windows user you can use Waitress server instead Gunicorn

 .. code:: bash

    $ pip install waitress
-    $ waitress-serve --port=8000 app:api
+    $ waitress-serve --port=8000 look.app


FYI, I modified this manually to resolve a merge conflict with the latest code in master.

kgriffs · 2017-01-17T22:52:01Z

docs/user/tutorial.rst

+Testing your application
+------------------------
+
+Up to this point we didn't care about tests, but when creating applications


I think we could make the second clause in this sentence more compelling. What do you think about something like the following?

Up to this point we didn't care about tests, but fully exercising your code is critical to creating robust applications with a great user experience.

kgriffs · 2017-01-17T23:09:48Z

docs/user/tutorial.rst

+Up to this point we didn't care about tests, but when creating applications
+that will be used by someone you should have those. So, as an exercise, we'll create
+the next piece of code in accordance with `Test Driven Development
+<http://www.obeythetestinggoat.com/book/praise.harry.html>`_


Given that this guide is Django-centric, is there a more generic TDD reference that we might use instead? Alternatively, it may make sense to include a note about how the linked guide uses Django for its examples, but the principles and workflow are the same, regardless of what web framework you use.

(Don't get me wrong, Django is a great choice for many use cases. I just want to make sure we are taking the reader's context into consideration.)

Hmm... this one is the best I know, even though I'm not a fan of Django :) I'll add a note with explanations.

kgriffs · 2017-01-18T01:08:48Z

docs/user/tutorial.rst

+they don't check anything more than ``test_posted_image_gets_saved``. But we can
+do that only because we have a very simple application logic.
+
+Normally, you would check component integration and few more meaningful logic paths


and few more meaningful logic paths

===>

and all primary logic paths

kgriffs · 2017-01-18T01:09:08Z

docs/user/tutorial.rst

+do that only because we have a very simple application logic.
+
+Normally, you would check component integration and few more meaningful logic paths
+through the entire application with functional tests, and leave the bulk of testing


"through" ===> "throughout"

kgriffs · 2017-01-18T01:11:50Z

docs/user/tutorial.rst

+
+Normally, you would check component integration and few more meaningful logic paths
+through the entire application with functional tests, and leave the bulk of testing
+to unit tests. But the actual ratio of unit/functional tests depend entirely on


"depend" ===> "depends"

"on applications problem domain and will vary." ===> "on each application's problem domain, and will vary."

kgriffs · 2017-01-18T01:14:41Z

docs/user/tutorial.rst

+to unit tests. But the actual ratio of unit/functional tests depend entirely on
+applications problem domain and will vary.
+
+After this section we won't be doing TDD anymore as you should have a good grip


"we won't be doing TDD anymore as you" ==> "we'll omit the TDD instructions, as you..."

kgriffs · 2017-01-18T01:14:57Z

docs/user/tutorial.rst

+applications problem domain and will vary.
+
+After this section we won't be doing TDD anymore as you should have a good grip
+of testing in Falcon by now. Instead, we'll focus on showcasing some more of the


"in Falcon" ===> "Falcon applications"

butla · 2017-01-18T08:48:57Z

@kgriffs Good that it's finally going somewhere :-) I'm quite busy now, but I'll try to go over your suggestions in a week or two.

kgriffs · 2017-02-03T18:44:57Z

@butla do you think you'll have some time to work on this over the next few days? It would be great to get this in the docs for 1.2 if we can.

butla · 2017-02-03T22:45:02Z

@kgriffs I may be able to work on this on Tuesday, if not, then definitely on Wednesday :)
Is that okay?

kgriffs · 2017-02-03T22:45:30Z

@butla cool, sounds good. Thanks!

butla · 2017-02-15T18:54:09Z

@kgriffs That was quite a thorough review you did there :)
I think I've fixed everything you wanted, but there are still some issues remaining:

using only PNG throughout the tutorial (I'm in favor of PNG, there was something odd about jpeg mimetype and .jpg files, but I don't remember anymore...)
sending the images through redirecting to "http" everywhere (I think I should do it, do you?)
the issue of strange import order in my code samples (more explanations in the comment somewhere above)

After all of those are resolved, I'll try to squash my commits and rebase onto the current master.

butla · 2017-02-16T14:50:32Z

Ok, so I've already did the changes with PNG as the image type everywhere and with sending the images with redirect to http.

I'll also try to squash and rebase my changes onto master on a different branch.

butla · 2017-02-16T15:49:07Z

All right, so if my changes are OK, I'll forcibly push my "squash" branch onto my "master", and this will be ready to merge... Once we resolve the issue of the strange import order in the code samples :) Or should I just put the imports in the order the tool wants it?

Oh, and one more thing, during squashing I've rephrased two sentences that looked clunky to me.
Here it is on the diff (the other change was done in the upstream)

butla@b2:~/development/falcon$ git diff master squash -- docs/user/tutorial.rst
diff --git a/docs/user/tutorial.rst b/docs/user/tutorial.rst
index 8025490..9a0a0f2 100644
--- a/docs/user/tutorial.rst
+++ b/docs/user/tutorial.rst
@@ -109,9 +109,9 @@ let's use something that you would actually deploy in production.

     $ pip install gunicorn
     $ gunicorn look.app
-
-Gunicorn has still limitation that is not working on Windows.
-If you are Windows user you can use Waitress server instead Gunicorn
+
+If you are a Windows user, then use Waitress instead of Gunicorn, since the latter
+doesn't work under Windows.

 .. code:: bash

@@ -1065,7 +1065,10 @@ such as `IPython <http://ipython.org/>`_ or

 Also, don't be shy about pulling up Falcon's source code on GitHub or in your
 favorite text editor. The team has tried to make the code as straightforward
-and readable as possible; where other documentation may fall short, the code basically
-"can't be wrong."
-
+and readable as possible; where other documentation may fall short, the code
+basically "can't be wrong."

+A number of Falcon add-ons, templates, and complimentary packages are
+available for use in your projects. We've listed several of these on the
+`Falcon wiki <https://github.com/falconry/falcon/wiki>`_ as a starting
+point, but you may also wish to search PyPI for additional resources.

kgriffs · 2017-03-03T21:23:00Z

Oh, and one more thing, during squashing I've rephrased two sentences that looked clunky to me.

Those changes LGTM. Thanks!

kgriffs · 2017-03-03T21:39:28Z

As I understand, PEP8 encourages standard/third-party/own (and alphabetical order in each section) import order.

When the Falcom framework tests run with flake8-import-order and --application-import-names=falcon the import falcon statement is expected to be grouped with the local module imports... Perhaps this is what is happening with examples/look/tests ?

All right, so if my changes are OK, I'll forcibly push my "squash" branch onto my "master", and this will be ready to merge

@butla Everything LGTM. Let's go ahead get this squashed. Thanks!

butla · 2017-03-07T16:05:07Z

@kgriffs Ok, that shed some light on the order but I was still left with a strange order (builtin -> local -> external -> falcon) in the test for the sample app.

import io
from unittest.mock import call, MagicMock, mock_open

import look.app
import look.images

import msgpack
import pytest

import falcon
from falcon import testing
import falcon.request_helpers

Anyway, I made the imports look like that, rebased onto the current master, and put that on my master, so it should be ready to merge.

kgriffs · 2017-03-07T19:08:13Z

OK, I think this is ready to merge! I can play around with the pep8 tox env to see if I can fix the import issue. I'll probably need to create some additional tox env(s) just for testing the example.

kgriffs added the needs-review label Nov 3, 2016

butla force-pushed the master branch from 1a407b1 to 525c057 Compare November 6, 2016 13:56

butla force-pushed the master branch 3 times, most recently from d17080f to 7863f8f Compare November 8, 2016 18:06

butla force-pushed the master branch 2 times, most recently from 4c68eef to e50bfbd Compare November 9, 2016 16:21

kgriffs requested review from kgriffs, fxfitz and jmvrbanac January 17, 2017 18:56

kgriffs requested changes Jan 18, 2017

View reviewed changes

doc(tutorial): Testing as part of the tutorial.

c5a8f4c

butla force-pushed the master branch from 5c49163 to c5a8f4c Compare March 7, 2017 15:57

kgriffs approved these changes Mar 7, 2017

View reviewed changes

kgriffs merged commit 73507b1 into falconry:master Mar 7, 2017

butla mentioned this pull request Mar 7, 2017

Add a testing tutorial to the docs #253

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Testing in the tutorial #934

Testing in the tutorial #934

butla commented Oct 27, 2016

codecov-io commented Nov 6, 2016 •

edited

Loading

butla commented Nov 8, 2016

butla commented Nov 9, 2016

butla commented Nov 30, 2016

kgriffs left a comment

kgriffs Jan 17, 2017

kgriffs Jan 17, 2017

kgriffs Jan 17, 2017

kgriffs Jan 17, 2017

butla Feb 9, 2017

kgriffs Jan 17, 2017

butla Feb 9, 2017

kgriffs Jan 18, 2017

kgriffs Jan 18, 2017

kgriffs Jan 18, 2017

kgriffs Jan 18, 2017

kgriffs Jan 18, 2017

butla commented Jan 18, 2017

kgriffs commented Feb 3, 2017

butla commented Feb 3, 2017

kgriffs commented Feb 3, 2017

butla commented Feb 15, 2017

butla commented Feb 16, 2017

butla commented Feb 16, 2017

kgriffs commented Mar 3, 2017

kgriffs commented Mar 3, 2017

butla commented Mar 7, 2017 •

edited

Loading

kgriffs commented Mar 7, 2017

Testing in the tutorial #934

Testing in the tutorial #934

Conversation

butla commented Oct 27, 2016

codecov-io commented Nov 6, 2016 • edited Loading

Codecov Report

butla commented Nov 8, 2016

butla commented Nov 9, 2016

butla commented Nov 30, 2016

kgriffs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

butla commented Jan 18, 2017

kgriffs commented Feb 3, 2017

butla commented Feb 3, 2017

kgriffs commented Feb 3, 2017

butla commented Feb 15, 2017

butla commented Feb 16, 2017

butla commented Feb 16, 2017

kgriffs commented Mar 3, 2017

kgriffs commented Mar 3, 2017

butla commented Mar 7, 2017 • edited Loading

kgriffs commented Mar 7, 2017

codecov-io commented Nov 6, 2016 •

edited

Loading

butla commented Mar 7, 2017 •

edited

Loading