adding documentation about pointing pytest at source files #1940

skylarjhdownes · 2016-09-15T22:26:08Z

Fixes #1937

Related to pytest-dev#1937

ref pytest-dev#1937

coveralls · 2016-09-15T22:37:02Z

Coverage remained the same at 93.079% when pulling f1faaea on skylarjhdownes:master into 863b7d0 on pytest-dev:master.

nicoddemus · 2016-09-15T22:37:59Z

doc/en/customize.rst

+
+If you place a conftest.py file in the root directory of your project
+(as determined by pytest, see above.) pytest will run tests against 
+the code below that directory by adding it to your sys.path instead of 


After a quick look I couldn't find any evidence in the sources of that... perhaps @RonnyPfannschmidt can chime in?

This is kind of a hack, which admittedly I've used and even advertised in the past. But it's a side-effect on the not very ideal way how we import conftest.py files currently. I'm rather hesitant to document it officially as then it becomes something we can not break in the future, while this is a domain where it would be very nice to clean up these side-effects. We shouldn't be doing such unexpected things with sys.path!

Just now getting back to this... Should I remove these paragraphs from the pull request then? They would have saved me a heck of a lot of grief. Perhaps the conftest.py thing should be mentioned as an unsupported side effect somehow, instead of a supported feature?

Either way, the thing I really think should be more clearly stated is that the user is expected to install the python code to be tested in develop mode. As a newb coming from using nose's sys.path hackery, that pattern was not at all obvious to me. I'm happy to shelve the conftest.py piece of this and focus on documenting the develop mode pattern.

Either way, the thing I really think should be more clearly stated is that the user is expected to install the python code to be tested in develop mode.

I think this is the heart of the matter; this is good practice and will be useful with any Python project (at least OS that is). So I think removing the sys.path hackery altogether is best in the long term.

As a newb coming from using nose's sys.path hackery

What if we mention this detail in nose.rst? This way users coming from nose will have an obvious place to understand the difference regarding how pytest finds the source code. We should instruct the user to create a virtual environment though, not mention about the sys.path implementation detail.

nicoddemus · 2016-09-15T22:39:24Z

Btw, Travis failed with:

/home/travis/build/pytest-dev/pytest/doc/en/getting-started.rst:189: WARNING: Title underline too short.

nicoddemus · 2016-09-15T22:40:54Z

doc/en/goodpractices.rst

     pip install -e .   # install package using setup.py in editable mode
+                        # similar to running python setup.py develop
+  
+  This installs your package with a symlink to your development code


nicoddemus · 2016-09-15T22:42:18Z

doc/en/getting-started.rst


    pytest --fixtures   # shows builtin and custom fixtures

+Contributing tests to an existing project


To be honest I would rather remove this entire session... it seems distracting and very narrow for a specific user case. I understand that was your use case, but nowadays IMHO people are used to virtualenvs in general (that includes venv and conda), so this in the end reads confusing to me, specially on the getting-started session.

I disagree on the 'people being used to virtualenvs' point, many users coming to a getting started section will not be used to any of the basic concepts of Python or unit testing. This being too specific/narrow makes sense to me though. It's kinda just tacked on the end at the moment.

Seems like running the tests on a new project will be enough people's first experience with pytest that there should be a walkthrough for it somewhere, and the getting started section was the first place I looked for it. Maybe there should be a page on it linked at the bottom?

I disagree on the 'people being used to virtualenvs' point, many users coming to a getting started section will not be used to any of the basic concepts of Python or unit testing.

You may be right, I'm probably biased on this. But perhaps this should be moved somewhere in goodpractices then? virtualenv, tox, etc are all mentioned there.

The pip install -e/setup.py develop concept is mentioned there already, and I don't think the whole "contributing to an existing repo" concept fits there. Hmm.

The only other place the develop concept is mentioned is the nose page.

nicoddemus · 2016-09-15T22:42:45Z

Hey @skylarjhdownes thanks for following up!

nicoddemus · 2016-09-15T23:18:22Z

doc/en/getting-started.rst

+flavor of version control and (optionally) setting up a virtualenv
+you will want to run::
+
+    pip install -e  # Environment dependent alternatives include 


I think we can add the full instructions here:

cd <repository> pip install -e .

(Note the . at the end)

coveralls · 2016-09-15T23:36:08Z

Coverage remained the same at 93.079% when pulling 330a2f6 on skylarjhdownes:master into 863b7d0 on pytest-dev:master.

coveralls · 2016-09-15T23:54:10Z

Coverage remained the same at 93.079% when pulling 34117be on skylarjhdownes:master into 863b7d0 on pytest-dev:master.

Moved the "Contributing tests to an existing project" section to it's own page.

nicoddemus · 2016-09-27T20:41:29Z

CHANGELOG.rst

 *

-*
+* Added documentation related to issue #1937 


Please make that reference a link, see #1934 above

nicoddemus · 2016-09-27T20:42:55Z

doc/en/customize.rst

+
+If you place a conftest.py file in the root directory of your project
+(as determined by pytest, see above.) pytest will run tests against 
+the code below that directory by adding it to your sys.path instead of 


Either way, the thing I really think should be more clearly stated is that the user is expected to install the python code to be tested in develop mode.

I think this is the heart of the matter; this is good practice and will be useful with any Python project (at least OS that is). So I think removing the sys.path hackery altogether is best in the long term.

nicoddemus · 2016-09-27T20:46:08Z

doc/en/customize.rst

+
+If you place a conftest.py file in the root directory of your project
+(as determined by pytest, see above.) pytest will run tests against 
+the code below that directory by adding it to your sys.path instead of 


As a newb coming from using nose's sys.path hackery

What if we mention this detail in nose.rst? This way users coming from nose will have an obvious place to understand the difference regarding how pytest finds the source code. We should instruct the user to create a virtual environment though, not mention about the sys.path implementation detail.

nicoddemus

Please see my comments above, I "accepted" the review by accident. 😁

coveralls · 2016-09-27T21:04:07Z

Coverage decreased (-0.1%) to 92.949% when pulling 1ab1962 on skylarjhdownes:master into 863b7d0 on pytest-dev:master.

coveralls · 2016-09-27T21:11:46Z

Coverage decreased (-0.1%) to 92.949% when pulling 3d211da on skylarjhdownes:master into 863b7d0 on pytest-dev:master.

skylarjhdownes · 2016-09-27T21:46:25Z

CHANGELOG.rst

 *

-*
+* Added documentation related to issue (`#1937`_)


Yes, but you still need to add a link down below:

.. _#1937: https://github.com/pytest-dev/pytest/issues/1937

Related to pytest-dev#1940

merwok · 2017-01-25T17:02:23Z

doc/en/existingtestsuite.rst

+Using pytest with an existing test suite
+===========================================
+
+Pytest can be used with most existing test suites, but it's 


RonnyPfannschmidt · 2017-04-06T21:42:10Z

@skylarjhdownes @nicoddemus it seems we let this one bit rot, can we try to revive it ?

coveralls · 2017-04-06T23:46:34Z

Coverage remained the same at 92.69% when pulling 3aa4fb6 on skylarjhdownes:master into c734a2d on pytest-dev:master.

coveralls · 2017-04-07T01:10:50Z

Coverage remained the same at 92.69% when pulling f7caa56 on skylarjhdownes:master into c734a2d on pytest-dev:master.

nicoddemus · 2017-04-07T02:03:52Z

Thanks a lot @skylarjhdownes for following up!

Fixed the linting error and some small formatting issues, so I think this is now good to go! 👍

coveralls · 2017-04-07T02:09:52Z

Coverage remained the same at 92.69% when pulling 4585238 on skylarjhdownes:master into c734a2d on pytest-dev:master.

coveralls · 2017-04-07T02:18:45Z

Coverage remained the same at 92.69% when pulling 4585238 on skylarjhdownes:master into c734a2d on pytest-dev:master.

coveralls · 2017-04-07T02:40:09Z

Coverage remained the same at 92.69% when pulling f2300fb on skylarjhdownes:master into c734a2d on pytest-dev:master.

RonnyPfannschmidt · 2017-04-07T05:11:18Z

@skylarjhdownes @nicoddemus great job in getting this finished up so quickly - thanks

skylarjhdownes added 8 commits September 15, 2016 10:46

documenting how to point pytest at local code

d217984

Related to pytest-dev#1937

fix spacing

383fc02

fix typo

69f72c6

add mention of setup.py develop

b4fd74c

clarified purpose of pip install -e command

07ad71e

ref pytest-dev#1937

add how-to for getting started on existing project

81a733f

ref pytest-dev#1937

Update AUTHORS

d781b76

Update CHANGELOG.rst

f1faaea

nicoddemus reviewed Sep 15, 2016

View reviewed changes

Update getting-started.rst

330a2f6

Update goodpractices.rst

34117be

skylarjhdownes added 2 commits September 27, 2016 12:51

Create existingtestsuite.rst

7e2f66a

remove existing tests stuff, add link to new page

12ac3c7

Moved the "Contributing tests to an existing project" section to it's own page.

nicoddemus requested changes Sep 27, 2016

View reviewed changes

nicoddemus approved these changes Sep 27, 2016

View reviewed changes

nicoddemus requested changes Sep 27, 2016

View reviewed changes

skylarjhdownes added 2 commits September 27, 2016 13:53

make issue pytest-dev#1934 reference a link

1ab1962

add existing test suite page to table of contents

3d211da

skylarjhdownes commented Sep 27, 2016

View reviewed changes

Update CHANGELOG.rst

b0c78c8

rjprins added a commit to rjprins/pytest that referenced this pull request Jan 13, 2017

Remove mention of --assert=reinterp in documentation

b34d9b5

Related to pytest-dev#1940

rjprins mentioned this pull request Jan 13, 2017

Remove mention of --assert=reinterp in documentation #2194

Merged

rjprins added a commit to rjprins/pytest that referenced this pull request Jan 13, 2017

Remove mention of --assert=reinterp in documentation

46a9861

Related to pytest-dev#1940

merwok reviewed Jan 25, 2017

View reviewed changes

Merge branch 'master' into master

3aa4fb6

moved documentation of conftest.py hack to nose.rst

f7caa56

nicoddemus added 3 commits April 6, 2017 22:59

Add missing link in CHANGELOG

639c592

Small formatting fixes to nose.rst

5462697

Fix small typo in docs

4585238

nicoddemus approved these changes Apr 7, 2017

View reviewed changes

Fix links in docs

f2300fb

nicoddemus merged commit 8c69d5c into pytest-dev:master Apr 7, 2017


		pytest --fixtures # shows builtin and custom fixtures

		Contributing tests to an existing project

Uh oh!

adding documentation about pointing pytest at source files #1940

adding documentation about pointing pytest at source files #1940

Uh oh!

Conversation

skylarjhdownes commented Sep 15, 2016

Uh oh!

coveralls commented Sep 15, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicoddemus commented Sep 15, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicoddemus commented Sep 15, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Sep 15, 2016

Uh oh!

coveralls commented Sep 15, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicoddemus left a comment

Choose a reason for hiding this comment

Uh oh!

coveralls commented Sep 27, 2016

Uh oh!

coveralls commented Sep 27, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RonnyPfannschmidt commented Apr 6, 2017

Uh oh!

coveralls commented Apr 6, 2017

Uh oh!

coveralls commented Apr 7, 2017

Uh oh!

nicoddemus commented Apr 7, 2017

Uh oh!

coveralls commented Apr 7, 2017

Uh oh!

coveralls commented Apr 7, 2017

Uh oh!

coveralls commented Apr 7, 2017

Uh oh!

RonnyPfannschmidt commented Apr 7, 2017

Uh oh!

Reviewers

Assignees