How to Submit Effective Bug Reports

To fix a bug, maintainers must be able to reproduce it quickly. To help us help you:

• Provide a minimal reproducible example: Reduce your HTML and Java code to the absolute minimum necessary to trigger the failure. Trimming extraneous code speeds up investigation significantly.
• Supply an automated JUnit test: Writing a failing test case allows maintainers to execute and verify the issue immediately.

Steps for Isolating JavaScript Errors

Follow these recommended steps to pin down the root cause:

1. Match target BrowserVersion: Ensure WebClient is instantiated with the same BrowserVersion as the real browser you are testing against.
2. Enable Debug Logging: Set the logger org.htmlunit.javascript to DEBUG level. This will log wrapped inline code, making stack traces easier to trace back to source files.
3. Use an Intercepting Proxy: Tools like Charles Proxy allow you to intercept HTTP responses and inject debugging statements (like alert()) into external JS files. Use Map Local features to substitute remote JavaScript files with modified local files.
4. Disable Browser Caching: Ensure your comparison browser fetches freshly modified scripts without caching.

Example: Diagnosing undefined errors:

org.htmlunit.corejs.javascript.EcmaError: TypeError: Cannot call method "getAttribute" of undefined
(http://example.com/js/app.js#16)

This indicates that the target variable evaluated to undefined prior to the getAttribute() call. Inspect the call stack in your proxy or browser developer tools to determine where the object initialization diverged.

Useful Injected JavaScript Debug Techniques

Inspecting Variable Values:

function myFunction(a, b) {
    var c = a + b;
    alert(c); // Compare output between HtmlUnit and a real browser
    return c;
}

Inspecting the Call Stack:

function myFunction(a, b) {
    alert(arguments.callee.caller); // Prints the outer caller function
    return a + b;
}

Conditional or Flagged Alert Logging:

var debug = false;

function testExecution() {
    debug = true; // Enable debug logging specifically for this pass
    myFunction(1, 2);
    debug = false;
}

function myFunction(a, b) {
    if (debug) {
        alert("myFunction called with: " + a + ", " + b);
    }
    return a + b;
}

Pull Request Rules and Guidelines

To minimize maintainer overhead and accelerate code review, all pull requests must follow these rules:

• Coding Conventions: Code must strictly follow our coding conventions. Run mvn checkstyle:checkstyle before submitting.
• Automated Unit Tests: No code changes will be merged without accompanying unit tests. When applicable, test classes should extend WebDriverTestCase to ensure cross-browser compatibility.
• Bug Fix Tests: Bug fixes must include a unit test that fails with the old behavior and passes with the fix applied.
• Existing Test Suite Pass: Ensure the full test suite passes locally or via your feature branch.
• License & Copyright: All original source files must carry the Gargoyle Software Inc. copyright notice and be licensed under the project's Apache License 2.0.
• JavaDoc & Author Tags: All public methods must include clear JavaDoc documentation. Add your name to the top-level @author block in chronological order when modifying existing classes.

IMPORTANT: Pull requests without accompanying unit tests will be rejected. If you need assistance constructing a WebDriver test case, post a question on your pull request draft or consult the Development Guide.

Additional documentation updates and example improvements are always greatly appreciated.