user/src/com/google/gwt/junit/RunStyleSelenium.java

/*
 * Copyright 2008 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.gwt.junit;

import com.google.gwt.core.ext.TreeLogger;
import com.google.gwt.core.ext.UnableToCompleteException;

import com.thoughtworks.selenium.DefaultSelenium;
import com.thoughtworks.selenium.Selenium;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Runs via browsers managed by Selenium.
 */
public class RunStyleSelenium extends RunStyle {

  /**
   * The maximum amount of time that a selenia can take to start in
   * milliseconds. 10 minutes.
   */
  private static final int LAUNCH_TIMEOUT = 10 * 60 * 1000;

  /**
   * Wraps a Selenium instance.
   */
  protected static interface SeleniumWrapper {
    void createSelenium(String domain);

    Selenium getSelenium();

    String getSpecifier();
  }

  /**
   * Implements SeleniumWrapper using DefaultSelenium. Visible for testing.
   */
  static class RCSelenium implements SeleniumWrapper {

    private static final Pattern PATTERN = Pattern.compile("([\\w\\.-]+):([\\d]+)/(.+)");

    /*
     * Visible for testing.
     */
    String browser;
    String host;
    int port;

    private Selenium selenium;
    private final String specifier;

    public RCSelenium(String specifier) {
      this.specifier = specifier;
      parseSpecifier();
    }

    public void createSelenium(String domain) {
      this.selenium = new DefaultSelenium(host, port, browser, domain);
    }

    public Selenium getSelenium() {
      return selenium;
    }

    public String getSpecifier() {
      return specifier;
    }

    private void parseSpecifier() {
      Matcher matcher = PATTERN.matcher(specifier);
      if (!matcher.matches()) {
        throw new IllegalArgumentException("Unable to parse Selenium target "
            + specifier + " (expected format is [host]:[port]/[browser])");
      }
      this.browser = matcher.group(3);
      this.host = matcher.group(1);
      this.port = Integer.parseInt(matcher.group(2));
    }
  }

  /**
   * A {@link Thread} used to interact with {@link Selenium} instances. Selenium
   * does not support execution of multiple methods at the same time, so its
   * important to make sure that {@link SeleniumThread#isComplete()} returns
   * true before calling more methods in {@link Selenium}.
   */
  class SeleniumThread extends Thread {

    /**
     * {@link RunStyleSelenium#lock} is sometimes active when calling
     * {@link #isComplete()}, so we need a separate lock to avoid deadlock.
     */
    Object accessLock = new Object();

    /**
     * The exception thrown while running this thread, if any.
     */
    private Throwable exception;

    /**
     * True if the selenia has successfully completed the action. Protected by
     * {@link #accessLock}.
     */
    private boolean isComplete;

    private final SeleniumWrapper remote;

    /**
     * Construct a new {@link SeleniumThread}.
     * 
     * @param remote the {@link SeleniumWrapper} instance
     */
    public SeleniumThread(SeleniumWrapper remote) {
      this.remote = remote;
      setDaemon(true);
    }

    /**
     * Get the {@link Throwable} caused by the action.
     * 
     * @return the exception if one occurred, null if none occurred
     */
    public Throwable getException() {
      synchronized (accessLock) {
        return exception;
      }
    }

    public SeleniumWrapper getRemote() {
      return remote;
    }

    public boolean isComplete() {
      synchronized (accessLock) {
        return isComplete;
      }
    }

    protected void markComplete() {
      synchronized (accessLock) {
        isComplete = true;
      }
    }

    protected void setException(Throwable e) {
      synchronized (accessLock) {
        this.exception = e;
        isComplete = true;
      }
    }
  }

  /**
   * <p>
   * The {@link Thread} used to launch a module on a single Selenium target. We
   * launch {@link Selenium} instances in a separate thread because
   * {@link Selenium#start()} can hang if the browser cannot be opened
   * successfully. Instead of blocking the test indefinitely, we use a separate
   * thread and timeout if needed.
   * </p>
   * <p>
   * We wait until {@link LaunchThread#isComplete()} returns <code>true</code>
   * before starting the keep alive thread or creating a {@link StopThread}, so
   * no other thread can be accessing {@link Selenium} at the same time.
   * </p>
   */
  class LaunchThread extends SeleniumThread {

    private final String moduleName;

    /**
     * Construct a new {@link LaunchThread}.
     * 
     * @param remote the remote {@link SeleniumWrapper} instance
     * @param moduleName the module to load
     */
    public LaunchThread(SeleniumWrapper remote, String moduleName) {
      super(remote);
      this.moduleName = moduleName;
    }

    @Override
    public void run() {
      SeleniumWrapper remote = getRemote();
      try {
        String domain = "http://" + getLocalHostName() + ":" + shell.getPort()
            + "/";
        String url = shell.getModuleUrl(moduleName);

        // Create the selenium instance and open the browser.
        shell.getTopLogger().log(TreeLogger.TRACE,
            "Starting with domain: " + domain + " Opening URL: " + url);
        remote.createSelenium(domain);
        remote.getSelenium().start();

        // We set the speed to 1000ms as a workaround a bug where Selenium#open
        // can hang.
        remote.getSelenium().setSpeed("1000");
        remote.getSelenium().open(url);
        remote.getSelenium().setSpeed("0");

        markComplete();
      } catch (Throwable e) {
        shell.getTopLogger().log(
            TreeLogger.ERROR,
            "Error launching browser via Selenium-RC at "
                + remote.getSpecifier(), e);
        setException(e);
      }
    }
  }

  /**
   * <p>
   * The {@link Thread} used to stop a selenium instance.
   * </p>
   * <p>
   * We stop the keep alive thread before creating {@link StopThread}s, and we
   * do not create {@link StopThread}s if a {@link LaunchThread} is still
   * running for a {@link Selenium} instance, so no other thread can possible be
   * accessing {@link Selenium} at the same time.
   * </p>
   */
  class StopThread extends SeleniumThread {

    public StopThread(SeleniumWrapper remote) {
      super(remote);
    }

    @Override
    public void run() {
      SeleniumWrapper remote = getRemote();
      try {
        remote.getSelenium().stop();
        markComplete();
      } catch (Throwable e) {
        shell.getTopLogger().log(TreeLogger.WARN,
            "Error stopping selenium session at " + remote.getSpecifier(), e);
        setException(e);
      }
    }
  }

  /**
   * The list of hosts that were interrupted. Protected by {@link #lock}.
   */
  private Set<String> interruptedHosts;

  /**
   * We keep a list of {@link LaunchThread} instances so that we know which
   * selenia successfully started. Only selenia that have been successfully
   * started should be stopped when the test is finished. Protected by
   * {@link #lock};
   */
  private List<LaunchThread> launchThreads = new ArrayList<LaunchThread>();

  /**
   * Indicates that testing has stopped, and we no longer need to run keep alive
   * checks. Protected by {@link #lock}.
   */
  private boolean stopped;

  private SeleniumWrapper remotes[];

  /**
   * A separate lock to control access to {@link Selenium}, {@link #stopped},
   * {@link #remotes}, and {@link #interruptedHosts}. This ensures that the
   * keepAlive thread doesn't call getTitle after the shutdown thread calls
   * {@link Selenium#stop()}.
   */
  private final Object lock = new Object();

  public RunStyleSelenium(final JUnitShell shell) {
    super(shell);
  }

  @Override
  public String[] getInterruptedHosts() {
    synchronized (lock) {
      if (interruptedHosts == null) {
        return null;
      }
      return interruptedHosts.toArray(new String[interruptedHosts.size()]);
    }
  }

  @Override
  public int initialize(String args) {
    if (args == null || args.length() == 0) {
      getLogger().log(TreeLogger.ERROR,
          "Selenium runstyle requires comma-separated Selenium-RC targets");
      return -1;
    }
    String[] targetsIn = args.split(",");
    SeleniumWrapper targets[] = new SeleniumWrapper[targetsIn.length];

    for (int i = 0; i < targets.length; ++i) {
      try {
        targets[i] = createSeleniumWrapper(targetsIn[i]);
      } catch (IllegalArgumentException e) {
        getLogger().log(TreeLogger.ERROR, e.getMessage());
        return -1;
      }
    }

    // We don't need a lock at this point because we haven't started the keep-
    // alive thread.
    this.remotes = targets;

    // Install a shutdown hook that will close all of our outstanding Selenium
    // sessions. The hook is only executed if the JVM is exited normally. If the
    // process is terminated, the shutdown hook will not run, which leaves
    // browser instances open on the Selenium server. We'll need to modify
    // Selenium Server to do its own cleanup after a timeout.
    Runtime.getRuntime().addShutdownHook(new Thread() {
      @Override
      public void run() {
        List<StopThread> stopThreads = new ArrayList<StopThread>();
        synchronized (lock) {
          stopped = true;
          for (LaunchThread launchThread : launchThreads) {
            // Closing selenium instances that have not successfully started
            // results in an error on the selenium client. By doing this check,
            // we are ensuring that no other calls to the remote instance are
            // being done by another thread.
            if (launchThread.isComplete()) {
              StopThread stopThread = new StopThread(launchThread.getRemote());
              stopThreads.add(stopThread);
              stopThread.start();
            }
          }
        }

        // Wait for all threads to stop.
        try {
          waitForThreadsToComplete(stopThreads, false, "stop", 500);
        } catch (UnableToCompleteException e) {
          // This should never happen.
        }
      }
    });
    return targets.length;
  }

  @Override
  public void launchModule(String moduleName) throws UnableToCompleteException {
    // Startup all the selenia and point them at the module url.
    for (SeleniumWrapper remote : remotes) {
      LaunchThread thread = new LaunchThread(remote, moduleName);
      synchronized (lock) {
        launchThreads.add(thread);
      }
      thread.start();
    }

    // Wait for all selenium targets to start.
    waitForThreadsToComplete(launchThreads, true, "start", 1000);

    // Check if any threads have thrown an exception. We wait until all threads
    // have had a change to start so that we don't shutdown while some threads
    // are still starting.
    synchronized (lock) {
      for (LaunchThread thread : launchThreads) {
        if (thread.getException() != null) {
          // The thread has already logged the exception.
          throw new UnableToCompleteException();
        }
      }
    }

    // Start the keep alive thread.
    start();
  }

  /**
   * Factory method for {@link SeleniumWrapper}.
   * 
   * @param seleniumSpecifier Specifies the Selenium instance to create
   * @return an instance of {@link SeleniumWrapper}
   */
  protected SeleniumWrapper createSeleniumWrapper(String seleniumSpecifier) {
    return new RCSelenium(seleniumSpecifier);
  }

  /**
   * Create the keep-alive thread.
   */
  protected void start() {
    // This will periodically check for failure of the Selenium session and stop
    // the test if something goes wrong.
    Thread keepAliveThread = new Thread() {
      @Override
      public void run() {
        do {
          try {
            Thread.sleep(1000);
          } catch (InterruptedException ignored) {
            break;
          }
        } while (doKeepAlives());
      }
    };
    keepAliveThread.setDaemon(true);
    keepAliveThread.start();
  }

  private boolean doKeepAlives() {
    synchronized (lock) {
      if (remotes != null) {
        // If the shutdown thread has already executed, then we can stop this
        // thread.
        if (stopped) {
          return false;
        }

        for (SeleniumWrapper remote : remotes) {
          // Use getTitle() as a cheap way to see if the Selenium server's still
          // responding (Selenium seems to provide no way to check the server
          // status directly).
          try {
            if (remote.getSelenium() != null) {
              remote.getSelenium().getTitle();
            }
          } catch (Throwable e) {
            // If we ask for the title of the page while a new module is
            // loading, IE will throw a permission denied exception.
            String message = e.getMessage();
            if (message == null
                || !message.toLowerCase().contains("permission denied")) {
              if (interruptedHosts == null) {
                interruptedHosts = new HashSet<String>();
              }
              interruptedHosts.add(remote.getSpecifier());
            }
          }
        }
      }
      return interruptedHosts == null;
    }
  }

  /**
   * Get the display list of specifiers for threads that did not complete.
   * 
   * @param threads the list of threads
   * @return a list of specifiers
   */
  private <T extends SeleniumThread> String getIncompleteSpecifierList(
      List<T> threads) {
    String list = "";
    for (SeleniumThread thread : threads) {
      if (!thread.isComplete()) {
        list += "  " + thread.getRemote().getSpecifier() + "\n";
      }
    }
    return list;
  }

  /**
   * Iterate over a list of {@link SeleniumThread}s, waiting for them to finish.
   * 
   * @param <T> the thread type
   * @param threads the list of threads
   * @param fatalExceptions true to treat all exceptions as errors, false to
   *          treat exceptions as warnings
   * @param action the action being performed by the thread
   * @param sleepTime the amount of time to sleep in milliseconds
   * @throws UnableToCompleteException if the thread times out and
   *           fatalExceptions is true
   */
  private <T extends SeleniumThread> void waitForThreadsToComplete(
      List<T> threads, boolean fatalExceptions, String action, int sleepTime)
      throws UnableToCompleteException {
    boolean allComplete;
    long endTime = System.currentTimeMillis() + LAUNCH_TIMEOUT;
    do {
      try {
        Thread.sleep(sleepTime);
      } catch (InterruptedException e) {
        // This should not happen.
        throw new UnableToCompleteException();
      }

      allComplete = true;
      synchronized (lock) {
        for (SeleniumThread thread : threads) {
          if (!thread.isComplete()) {
            allComplete = false;
          }
        }
      }

      // Check if we have timed out.
      if (!allComplete && endTime < System.currentTimeMillis()) {
        allComplete = true;
        String message = "The following Selenium instances did not " + action
            + " within " + LAUNCH_TIMEOUT + "ms:\n";
        synchronized (lock) {
          message += getIncompleteSpecifierList(threads);
        }
        if (fatalExceptions) {
          shell.getTopLogger().log(TreeLogger.ERROR, message);
          throw new UnableToCompleteException();
        } else {
          shell.getTopLogger().log(TreeLogger.WARN, message);
        }
      }
    } while (!allComplete);
  }
}