Reviewed by Darin.
[WebKit-https.git] / WebKitTools / iExploder / README.txt
1 iExploder 1.2.0
2 ===============
3
4 Welcome to iExploder. a highly inefficient, but fairly effective web
5 browser tester. The code still has a lot of work to be done, but it's
6 definitely usable. Here are some notable features:
7
8 * Tests all common HTML and CSS tags and attributes, as parsed from 
9 the KHTML and Mozilla source trees, as well as tags for Internet Explorer
10 from MSDN. This also includes a few Javascript hooks.
11 * Numeric, and String overflow and formatting tests
12 * Sequential and Randomized Test Case Generation
13 * Test Case Lookups
14 * Subtest generation (very weak right now)
15
16
17
18 Installation instructions:
19 --------------------------
20 Make sure you have Ruby installed (comes with Mac OS X, most Linux
21 distributions). See http://www.ruby-lang.org/ if you do not.
22
23 Copy the contents of the htdocs/ folder to any directory served
24 by your webserver. Make sure that directory can execute CGI scripts.
25
26
27
28 FAQ:
29 ----
30 1) Does it work with mod_ruby?
31
32   Yes, it's actually recommended for boosting performance. 
33
34 2) Are the tests always the same? 
35
36   The test cases should always be the same on a single installation, but not
37 necessarily on different installations of iExploder. Random generator seeds
38 may differ between operating systems and platforms.
39
40
41 3) How do I look up the last successful test for a client?
42
43   Use tools/lasthit.rb. When I get a crash, I usually do something like:
44
45 tail -15000 /var/log/apache2/access_log | ./lasthit.rb
46
47 Letting you know how many tests and what the last test id was for each
48 client tested. You can then try to repeat the test, or go through the
49 subtests to see if you can repeat the crash.
50
51 4) How do subtests work?
52
53   Pretty badly right now. If you have a page that crashes, you can resubmit
54 it with subtest=1, iexploder will try to pick out the particular tag that
55 crashes your browser (up to $maxTags). Often times, none of the subtests
56 will crash the browser, but the entire test will. This has a lot of room for
57 improvement.
58
59 5) How come I can't seem to repeat the crash?
60
61   Many browser crashes are race conditions that are not easy to repeat. Some
62 crashes only happen when going from test 4 -> test 5 -> test 6. If you can't
63 repeat the crash through subtests or a lookup of the failing test, try going
64 back a few tests.
65
66 It is also possible (but unliely) that your browser crashed while trying to load
67 the next test in the list, and your webserver did not log that hit yet.
68
69 6) Why did you write this?
70
71   I wanted to make sure that FireFox had as many bugs fixed in it as possible
72 before the 1.0 release. After 1.0 came out, I kept improving it.
73
74 7) Why is the code so awful?
75
76   I wrote this as a quick hack sitting in a hotel room one day while I was
77 waiting for some people to show up. It now represents the worst Ruby code
78 I have ever written. Heck, it looks as bad as Perl!
79
80 7) Why does Internet Explorer run the tests so slowly?
81
82   <META> refresh tags are very fragile in Internet Explorer, and can be easily
83 be rendered useless by other tags on the page. If this happens, a javascript
84 refresh will execute after a 1 second delay.