It took me a while to read through the idle_test documentation to figure out how to run the test. Similar to the Profiler documentation, I've added "Instant User's Manual" section at the top of the file, as well as edited the text and formatting a bit.

Although the text is aimed at people writing tests, I agree with starting with a new short section "0. Running all Idle tests".  The sentence already there is specific to automated unittests.  There is also a separate human-mediated test system run with "python -m idlelib.idle_test.htest" (more below).  This command should be added in this section.

Retesting, "python -m test.test_idle" on the command line no longer works for me on installed 3.4.3, Win7.  Instead I get

c:\Programs\Python34\python.exe: Error while finding spec for 'test.test_idle' (<class 'AttributeError'>: 'module' object has no attribute '__path__')

Did you get this or is does my install have a problem?  Running test_idle.py from the Idle editor works fine.  ">python -m test -v test_idle" fails with no output.

Onward: I do not want to indent code because I want people, including myself, to be able to cut and paste.  Some of the other edits look good at first glance.  I may have questions on some.

Something needs to be added to README about human-mediated tests, beyond the bottom-line summary in section 0.  There is a page long docstring in htest.py.  I am not sure how much to move to or duplicate in README (after further editing).  Any opinion, as a naive reader?

I'll add a note about running the human-mediated tests to section 0.

Running "python -m test.test_idle" for 64-bit 3.4.3 on Windows 7 works fine for me ("Ran 142 tests in 0.605s OK")

I'll take out the indented code. You make a good point about copy/paste.

I've added section 4 on human-mediated tests. I'd like to take a crack at improving the documentation a bit in htest.py before figuring out what to add to section 4. This can be addressed in a later patch.

New changeset 19e111891e39 by Terry Jan Reedy in branch '2.7':
Issue #23964: Update idlelib/idle_test/README.txt. first patch by Al Sweigart.
https://hg.python.org/cpython/rev/19e111891e39

New changeset 35b84ba2f8b1 by Terry Jan Reedy in branch '3.4':
Issue #23964: Update idlelib/idle_test/README.txt. first patch by Al Sweigart.
https://hg.python.org/cpython/rev/35b84ba2f8b1

Thanks for the push. I incorporated most of your suggestions and added more changes.