[Zope3-dev] Re: zope.testbrowser and mechanize

[Benji York]

Chris Withers wrote:
> Benji York wrote:
>>>> I actually don't want to support any exposure of mechanize 
>>>> functionality in zope.testbrowser.  Mechanize is an implementation 
>>>> detail (although a very important one) and may change in the future.
>>>
>>> I think the documentation I added makes this clear.
>>
>> It doesn't, 
> 
> """
> testbrowser currently doesn't help much unless you already know the
> controls you will be looking for, however, you can do some
> introspection by utilizing the underlying mechanize functionality.
> """
> 
> """
>     Unfortunately, testbrowser doesn't really support what you need,
>     so you have to use the underlying mechanize control:
> """
> 
> Both of those are pretty clear to me in explaining that you have to use 
> the "implementation detail" to get stuff done.

They are clear in what they say, but they do not say that a user of 
zope.testbrowser shouldn't depend on them and that they may go away at 
any time.  Even if it did I don't think that would be sufficient, I 
don't think the docs should mention mechanize (or any other unofficial 
parts of the API) at all.  I wonder what other's opinions are on this.

>> and it shouldn't.  It should be undocumented.
>
> Great, so you advocate forcing people to dig through the code and find 
> their own way blindly to do something as simple us uploading a file. Nice.

No, I advocate being very clear about what we intend to support.  I also 
advocate fixing missing/broken features or removing them.

> I put that stuff in there to give other people in my position a clue, I 
> was happy to get an off-list email saying thanks from Gary Poster. I'm a 
> bit perplexed to now have you bitching at me...

Perhaps I'm not communicating well, but I intend this to be a technical 
discussion, not a personal attack.  I do appreciate your help and 
feedback.  That doesn't change the fact that not every potential change 
is an improvement.

> So how, specifically, would I use XPath to find all checkbox controls in 
> a form?

I don't have time to look up the syntax at the moment.

> I'm more than happy to make it explicit in the stuff I added that these 
> aren't features and will go away as soon as something better is 
> abailable in testbrowser.

I'll reiterate my position that the text in question shouldn't be 
included.  Hopefully we'll get some feedback from other people on the 
list after the long (in the U.s.) holiday weekend.

>> That's not how "implementation details" work.
> 
> huh?

An implementation detail should not be counted on.  Documentation should 
include only those properties of the code which can be counted on.  It 
is more harmful to induce people into counting on implementation details 
that may very well change than it is to elide the detail in the docs.

>>> - testbrowser itself provides a way for doing decent introspection.
>>
>> We don't know what the right way is.  This is why it provides the 
>> .contents attribute. 
> 
> ...which doesn't help ;-)

Having access to the HTML allows you to bring to bear whatever 
introspection tools you deem appropriate.

>> With that you can use Beautiful Soup, libxml2, ElementTree, or whatever. 
> 
> What? instead of mechanize?

Actually in this case ClientForm, a different implementation detail.

>> We don't know enough to make the decision, so 
> 
> who is "we" here?

The people who have contributed to the design of zope.testbrowser and to 
Zope 3's functional testing infrastructure in general.

>> This is true, so as above, either the feature should be fixed or 
>> reference to it removed from the docs.
> 
> great, so now you want to withdraw file upload support from testbrowser?

That or fix it.

>> You don't compensate for a broken/missing feature by documenting a 
>> hack.  Please remove the offending text.
> 
> I won't. If you do, I'll take that as a clear sign that participation in 
> testbrowser's development isn't welcome and go and develop something 
> else or just plain fork it.

I'll wait until we get more feedback from others on this.
-- 
Benji York
Senior Software Engineer
Zope Corporation