You are viewing a plain text version of this content. The canonical link for it is here.
Posted to test-dev@httpd.apache.org by David Wheeler <da...@kineticode.com> on 2003/07/07 21:35:47 UTC
Re: Apache::TestRequest Doc Patch
On Monday, June 23, 2003, at 05:08 AM, Geoffrey Young wrote:
>> I especially need help with the "keep_alive" parameter to user_agent()
>
> keep_alive enables connection persistence, where the same connection
> is used to process multiple requests. the only use of it that I have
> seen is in http11/basicauth.t
>
> my $request_num = Apache::TestRequest::user_agent_request_num($res);
>
> ok $request_num == 3; #1 => no credentials
> #2 => 401 response with second request
> #3 => 200 with guest/guest credentials
>
> also, from the LWP::UserAgent manpage:
>
> The C<keep_alive> option also has the effect of loading and enabling
> the new experimental HTTP/1.1 protocol module.
>
> so keep_alive may be more of a shorthand way of enabling (and testing)
> HTTP/1.1 compliance rather than just persistent connections (which can
> be used in both protocols).
>
> as for the code changes, Stas should probably review them first.
> however, the docs look great - nice work.
Thanks Geoffrey. I've added in your comments, and attach a new patch.
Again, here's what it does:
* Attempts to document all of the important functions of
Apache::TestRequest. Comments and corrections would be much
appreciated. I especially need help with a description of what
OPTIONS() does.
* Exports UPLOAD from Apache::TestRequest. Was this an oversight?
* Changes the way the redirect_ok parameter works so that it affects
only that _that call_ to the function. Afterward it should revert to
the old value of $RedirectOK. I use local() to do this.
* Changes user_agent() so that the LWP::UserAgent
"requests_redirectable" parameter actually does something useful
vis-à-vis $RedirectOK.
* Added "SEE ALSO" section to Apache::Test. Note that this section, and
the same section of Apache::TestRequest, points to Apache::TestMM,
which currently has no documentation.
Regards,
David
--
David Wheeler AIM: dwTheory
david@kineticode.com ICQ: 15726394
http://kineticode.com/ Yahoo!: dew7e
Jabber: Theory@jabber.org
Kineticode. Setting knowledge in motion.[sm]
Re: Apache::TestRequest Doc Patch
Posted by David Wheeler <da...@kineticode.com>.
On Friday, July 18, 2003, at 09:03 AM, Stas Bekman wrote:
> The main reason that the default docroot is t/ is because things like
> logs/, conf/, etc are conveniently placed under t/. I'm not quite sure
> why do you think that most people will want to have the ../t as the
> serverroot. The only drawback of using t/ is in the need to adjust
> @INC, to include ../t.
Yes, I noticed this. . cannot be the serverroot because then, if the
module maintainer created conf and htdocs directories, they would be
indexed by the CPAN indexer, and that's a bad thing. If they're in t/,
the indexer ignores them.
But I'm not saying that I want ../t to be the ServerRoot. I'm saying
that traditionally, the distribution root was the cwd for the test
scripts in t/. Those are two different things, though I can see the
convenience of thinking of them the same. At any rate, if t/ remains
the default cwd for the test scripts as they are run, that should be
documented, as it varies from what the module author usually expects --
including from the behavior of the old Apache::test.
Regards,
David
--
David Wheeler AIM: dwTheory
david@kineticode.com ICQ: 15726394
http://kineticode.com/ Yahoo!: dew7e
Jabber: Theory@jabber.org
Kineticode. Setting knowledge in motion.[sm]
Re: Apache::TestRequest Doc Patch
Posted by Stas Bekman <st...@stason.org>.
>> I thought I've answered this question already:
>> http://marc.theaimsgroup.com/?l=apache-test-dev&m=105772914901179&w=2
>
>
> Right, so you did. I would just argue that it should default to the
> distribution root, but I won't push it. I'm adding this to my Makefile.PL:
>
> use FindBin;
> push @ARGV, '-serverroot', $FindBin::Bin;
Alternatively you can do this from t/TEST.PL:
$Apache::TestConfig::Argv{'-serverroot'} = catdir $FindBin::Bin, "..";
> Most CPAN module maintainers will want to know about this, I expect.
> I'll supply a doc patch with this information later today.
The main reason that the default docroot is t/ is because things like logs/,
conf/, etc are conveniently placed under t/. I'm not quite sure why do you
think that most people will want to have the ../t as the serverroot. The only
drawback of using t/ is in the need to adjust @INC, to include ../t.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: Apache::TestRequest Doc Patch
Posted by Stas Bekman <st...@stason.org>.
David Wheeler wrote:
> On Friday, July 18, 2003, at 07:22 AM, David Wheeler wrote:
>
>>> Done. They will probably require more polishing...
>>
>>
>> Cool, thanks, I'll take a look in a bit.
>
>
> I applied just a bit of polishing. Note that POD has an F<> tag that's
> used for identifying files. This is better than using I<>, which means
> italic, of course.
Certainly. I did two tweaks:
- s/F<.PL>/I<.PL>/ since it is not a file
- I have restored the leading /^\s\s/ in the synopsys, since we want the whole
section to be rendered as a single block and not separate blocks.
Thanks David.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: Apache::TestRequest Doc Patch
Posted by David Wheeler <da...@kineticode.com>.
On Friday, July 18, 2003, at 07:22 AM, David Wheeler wrote:
>> Done. They will probably require more polishing...
>
> Cool, thanks, I'll take a look in a bit.
I applied just a bit of polishing. Note that POD has an F<> tag that's
used for identifying files. This is better than using I<>, which means
italic, of course.
Regards,
David
--
David Wheeler AIM: dwTheory
david@kineticode.com ICQ: 15726394
http://kineticode.com/ Yahoo!: dew7e
Jabber: Theory@jabber.org
Kineticode. Setting knowledge in motion.[sm]
Re: Apache::TestRequest Doc Patch
Posted by David Wheeler <da...@kineticode.com>.
On Friday, July 18, 2003, at 01:37 AM, Stas Bekman wrote:
> Done. They will probably require more polishing...
Cool, thanks, I'll take a look in a bit.
> I thought I've answered this question already:
> http://marc.theaimsgroup.com/?l=apache-test-dev&m=105772914901179&w=2
Right, so you did. I would just argue that it should default to the
distribution root, but I won't push it. I'm adding this to my
Makefile.PL:
use FindBin;
push @ARGV, '-serverroot', $FindBin::Bin;
Most CPAN module maintainers will want to know about this, I expect.
I'll supply a doc patch with this information later today.
Regards,
David
--
David Wheeler AIM: dwTheory
david@kineticode.com ICQ: 15726394
http://kineticode.com/ Yahoo!: dew7e
Jabber: Theory@jabber.org
Kineticode. Setting knowledge in motion.[sm]
Re: Apache::TestRequest Doc Patch
Posted by Stas Bekman <st...@stason.org>.
David Wheeler wrote:
> On Tuesday, July 15, 2003, at 01:18 PM, Stas Bekman wrote:
>
>> It's trivial. If your webserver supports only the following methods:
>> GET and HEAD, OPTIONS, but not POST. the request OPTIONS will return a
>> response with a header Allow: OPTIONS GET HEAD
>
>
> Oh, I get it. See the enclosed patch, then.
Thanks David, committed with a few tweaks.
>> I guess I can take care of it. Just let me know which options are the
>> most urgent that you need to work with.
>
>
> Most important to me are:
>
> require Apache::TestMM;
> require Apache::TestRunPerl;
> Apache::TestMM->import(qw(test clean));
> Apache::TestMM::filter_args();
> Apache::TestRunPerl->generate_script();
Done. They will probably require more polishing...
> If there's an option to get the generated script to run the tests from
> the distribution root instead of t/, that'd be great to know about. And
> if there isn't, it should be documented that the tests will be run from
> t/, and that this is different from how CPAN modules traditionally work
> (only Perl itself runs tests from t/).
I thought I've answered this question already:
http://marc.theaimsgroup.com/?l=apache-test-dev&m=105772914901179&w=2
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: Apache::TestRequest Doc Patch
Posted by David Wheeler <da...@kineticode.com>.
On Tuesday, July 15, 2003, at 01:18 PM, Stas Bekman wrote:
> It's trivial. If your webserver supports only the following methods:
> GET and HEAD, OPTIONS, but not POST. the request OPTIONS will return a
> response with a header Allow: OPTIONS GET HEAD
Oh, I get it. See the enclosed patch, then.
> I guess I can take care of it. Just let me know which options are the
> most urgent that you need to work with.
Most important to me are:
require Apache::TestMM;
require Apache::TestRunPerl;
Apache::TestMM->import(qw(test clean));
Apache::TestMM::filter_args();
Apache::TestRunPerl->generate_script();
If there's an option to get the generated script to run the tests from
the distribution root instead of t/, that'd be great to know about. And
if there isn't, it should be documented that the tests will be run from
t/, and that this is different from how CPAN modules traditionally work
(only Perl itself runs tests from t/).
Thanks!
David
--
David Wheeler AIM: dwTheory
david@kineticode.com ICQ: 15726394
http://kineticode.com/ Yahoo!: dew7e
Jabber: Theory@jabber.org
Kineticode. Setting knowledge in motion.[sm]
Re: Apache::TestRequest Doc Patch
Posted by Stas Bekman <st...@stason.org>.
David Wheeler wrote:
>> re: OPTIONS, see section 9.2 in http://www.faqs.org/rfcs/rfc2616.html
[...]
>> for my $url (@urls) {
>> my $res = OPTIONS $url;
>> ok $res->code == 200;
>> my $allow = $res->header('Allow') || '';
>> ok $allow =~ /OPTIONS/;
>> }
>
>
> I still don't understand what it does or what it's for. Sorry. Someone
> else will likely have to document it.
It's trivial. If your webserver supports only the following methods: GET and
HEAD, OPTIONS, but not POST. the request OPTIONS will return a response with a
header Allow: OPTIONS GET HEAD
>> Looking forward for more docs ;)
>
>
> We'll see if I find any more tuits in the next few weeks. The only one
> I'm likely to contribute to in the short term is Apache::TestMM. And I
> don't understand it too well at this point, anyway.
I guess I can take care of it. Just let me know which options are the most
urgent that you need to work with.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: Apache::TestRequest Doc Patch
Posted by David Wheeler <da...@kineticode.com>.
On Wednesday, July 9, 2003, at 01:02 AM, Stas Bekman wrote:
> Thank you very much David, I've committed your patches and the docs.
> In the future please try to submit each feature change separately.
> Thanks.
Okay, no problem.
> re: OPTIONS, see section 9.2 in http://www.faqs.org/rfcs/rfc2616.html
>
> this is how httpd-test uses it:
>
> #httpd-test/perl-framework/t/apache/options.t
> use strict;
> use warnings FATAL => 'all';
>
> use Apache::Test;
> use Apache::TestRequest;
>
> my @urls = qw(/);
>
> plan tests => @urls * 2, \&have_lwp;
>
> for my $url (@urls) {
> my $res = OPTIONS $url;
> ok $res->code == 200;
> my $allow = $res->header('Allow') || '';
> ok $allow =~ /OPTIONS/;
> }
I still don't understand what it does or what it's for. Sorry. Someone
else will likely have to document it.
> So I've trimmed all the OPTIONS entries in the doc, but the main one.
> I think the rest aren't useful at all.
Okay.
> re: =head1 SYNOPSIS
>
> I'd suggest to have a small synopsis with mod_perl 1 and another on
> mod_perl 2? Or have no mod_perl specific api at all?
It's currently not specific, and it doesn't seem to me like it needs to
be specific.
> I didn't modify the content, but mainly adding C<> for modules and
> re-wrapping as a result (just pod fixups). Hopefully I'll have a
> chance to read through once I catch up with the emails backlog. For
> now I've just committed as is.
Okay.
> For the next pass, it'd be cool to move =item to be =head3 so that the
> items will appear in the TOC when rendered in HTML. That's the
> practice I've started to use on the perl.apache.org and it seems to do
> pretty well.
I usually do that, too. Next time.
> Looking forward for more docs ;)
We'll see if I find any more tuits in the next few weeks. The only one
I'm likely to contribute to in the short term is Apache::TestMM. And I
don't understand it too well at this point, anyway.
Regards,
David
--
David Wheeler AIM: dwTheory
david@kineticode.com ICQ: 15726394
http://kineticode.com/ Yahoo!: dew7e
Jabber: Theory@jabber.org
Kineticode. Setting knowledge in motion.[sm]
Re: Apache::TestRequest Doc Patch
Posted by Stas Bekman <st...@stason.org>.
David Wheeler wrote:
> On Monday, June 23, 2003, at 05:08 AM, Geoffrey Young wrote:
>
>>> I especially need help with the "keep_alive" parameter to user_agent()
>>
>>
>> keep_alive enables connection persistence, where the same connection
>> is used to process multiple requests. the only use of it that I have
>> seen is in http11/basicauth.t
>>
>> my $request_num = Apache::TestRequest::user_agent_request_num($res);
>>
>> ok $request_num == 3; #1 => no credentials
>> #2 => 401 response with second request
>> #3 => 200 with guest/guest credentials
>>
>> also, from the LWP::UserAgent manpage:
>>
>> The C<keep_alive> option also has the effect of loading and enabling
>> the new experimental HTTP/1.1 protocol module.
>>
>> so keep_alive may be more of a shorthand way of enabling (and testing)
>> HTTP/1.1 compliance rather than just persistent connections (which can
>> be used in both protocols).
>>
>> as for the code changes, Stas should probably review them first.
>> however, the docs look great - nice work.
>
>
> Thanks Geoffrey. I've added in your comments, and attach a new patch.
> Again, here's what it does:
>
> * Attempts to document all of the important functions of
> Apache::TestRequest. Comments and corrections would be much appreciated.
> I especially need help with a description of what OPTIONS() does.
>
> * Exports UPLOAD from Apache::TestRequest. Was this an oversight?
I guess it just wasn't used?
> * Changes the way the redirect_ok parameter works so that it affects
> only that _that call_ to the function. Afterward it should revert to the
> old value of $RedirectOK. I use local() to do this.
>
> * Changes user_agent() so that the LWP::UserAgent
> "requests_redirectable" parameter actually does something useful
> vis-à-vis $RedirectOK.
>
> * Added "SEE ALSO" section to Apache::Test. Note that this section, and
> the same section of Apache::TestRequest, points to Apache::TestMM, which
> currently has no documentation.
Thank you very much David, I've committed your patches and the docs. In the
future please try to submit each feature change separately. Thanks.
re: OPTIONS, see section 9.2 in http://www.faqs.org/rfcs/rfc2616.html
this is how httpd-test uses it:
#httpd-test/perl-framework/t/apache/options.t
use strict;
use warnings FATAL => 'all';
use Apache::Test;
use Apache::TestRequest;
my @urls = qw(/);
plan tests => @urls * 2, \&have_lwp;
for my $url (@urls) {
my $res = OPTIONS $url;
ok $res->code == 200;
my $allow = $res->header('Allow') || '';
ok $allow =~ /OPTIONS/;
}
So I've trimmed all the OPTIONS entries in the doc, but the main one. I think
the rest aren't useful at all.
---
re: =head1 SYNOPSIS
I'd suggest to have a small synopsis with mod_perl 1 and another on mod_perl
2? Or have no mod_perl specific api at all?
---
I didn't modify the content, but mainly adding C<> for modules and re-wrapping
as a result (just pod fixups). Hopefully I'll have a chance to read through
once I catch up with the emails backlog. For now I've just committed as is.
For the next pass, it'd be cool to move =item to be =head3 so that the items
will appear in the TOC when rendered in HTML. That's the practice I've started
to use on the perl.apache.org and it seems to do pretty well.
Looking forward for more docs ;)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com