commit 5d155c75db298687a216bb079bdf7588af0dc52a
parent b1d53118988a642117047a3896c11fabd40a35f8
Author: Martin von Gagern <gagern@ma.tum.de>
Date: Mon, 22 Jun 2015 19:30:26 +0200
Switch from own docker image to standard selenium images
Since the Selenium images are available for download, and downloading them
is usually faster than building them from scratch, this makes taking
screenshots easier. Furthermore, since the Selenium image is not specific
to KaTeX, it could as well be used for other purposes, thus saving space
since a single image can be used in multiple projects.
This change also deals with the non-determinism in the Lap screenshot:
We detect the one known (and accepted) alternate rendering and change the
output file name to Lap_alt in this case. So either Lap or Lap_alt gets
saved to, and if the image is different from both, then one of these files
will show a modification. On the other hand, if it is equal to either of
these, then the matching one will get overwritten, showing no change.
Diffstat:
8 files changed, 326 insertions(+), 142 deletions(-)
diff --git a/dockers/Screenshotter/Dockerfile b/dockers/Screenshotter/Dockerfile
@@ -1,14 +0,0 @@
-FROM ubuntu:14.04
-MAINTAINER xymostech <xymostech@gmail.com>
-RUN apt-get -qq update
-RUN apt-get -qqy install default-jre=2:1.7-51 firefox=28.0+build2-0ubuntu2 xvfb=2:1.15.1-0ubuntu2 wget=1.15-1ubuntu1 python=2.7.5-5ubuntu3 python-pip=1.5.4-1 nodejs=0.10.25~dfsg2-2ubuntu1 || true
-RUN wget http://selenium-release.storage.googleapis.com/2.43/selenium-server-standalone-2.43.0.jar
-RUN ln -s /usr/bin/nodejs /usr/bin/node
-RUN pip install selenium pypng
-ENV DISPLAY :1
-CMD /bin/bash ~/run.sh
-RUN echo "java -jar /selenium-server-standalone-2.43.0.jar > /dev/null &" >> ~/run.sh
-RUN echo "Xvfb :1 2> /dev/null &" >> ~/run.sh
-RUN echo "make -C /KaTeX serve > /dev/null &" >> ~/run.sh
-RUN echo "sleep 2" >> ~/run.sh
-RUN echo "/KaTeX/dockers/Screenshotter/screenshotter.py /KaTeX/test/screenshotter/ss_data.json" >> ~/run.sh
-\ No newline at end of file
diff --git a/dockers/Screenshotter/README.md b/dockers/Screenshotter/README.md
@@ -1,29 +1,65 @@
-### How to generate screenshotter images
-----------------------------------------
+# How to generate screenshotter images
+
+## Automatic generation of screen shots
Now you too can generate screenshots from your own computer, and (hopefully)
-have them look mostly the same as the current ones! To start, make a docker
-image from the included Dockerfile using a command like
+have them look mostly the same as the current ones! Make sure you have docker
+installed and running. Also make sure that the development server is running,
+or start it by running
+
+ node server.js
+
+in the top level directory of the source tree. If all you want is (re)create
+all the snapshots for all the browsers, then you can do so by running the
+`screenshotter.sh` script:
+
+ dockers/Screenshotter/screenshotter.sh
+
+It will fetch all required selenium docker images, and use them to
+take screenshots.
+
+## Manual generation
+
+If you are creating screenshots on a regular basis, you can keep the
+docker containers with the selenium setups running. Essentially you
+are encouraged to reproduce the steps from `screenshotter.sh`
+manually. Example run for Firefox:
+
+ container=$(docker run -d -P selenium/standalone-firefox:2.46.0)
+ node dockers/Screenshotter/screenshotter.js -b firefox -c ${container}
+ # possibly repeat the above command as often as you need, then eventually
+ docker stop ${container}
+ docker rm ${container}
+
+## Use without docker
+
+It is possible to run `screenshotter.js` without the use of Docker:
- docker build --tag=ss .
+ npm install selenium-webdriver
+ node dockers/Screenshotter/screenshotter.js
-from within this directory (note you need to have docker installed and running
-for this to work). This will build a docker image with the `ss` tag, which you
-can then use to run dockers based on it.
+This will generate screenshots using the Firefox installed on your system.
+Browsers other than Firefox can be targeted using the `--browser` option.
+For a complete list of options pass `--help` as an argument to
+`screenshotter.js`. Using these it should be possible to have the script
+connect to almost any Selenium web driver you might have access to.
-This Dockerfile is set up such that it will run everything and generate all the
-screenshots when the docker is run, so no interactive input is required. All
-that you need to do is mount the KaTeX directory you want to test into the
-`/KaTeX` directory in the docker, and run the `ss` docker, like so:
+Note that screenshots taken without Docker are very likely to disagree
+from the ones stored in the repository, due to different versions of
+various software components being used. The screenshots taken in this
+fashion are well suited for visual inspection, but for exact binary
+comparisons it would be neccessary to carefully set up the environment
+to match the one used by the Docker approach.
- docker run --volume=/your/KaTeX/:/KaTeX ss
+## Choosing the list of test cases
-The `--volume=/your/KaTeX:/KaTeX` switch mounts your KaTeX directory into the
-docker. Note this is a read-write mounting, so the new screenshots will be
-directly placed into your KaTeX directory.
+Both `screenshotter.js` and `screenshotter.sh` will accept
+an `--include` option (short `-i`) which can be used to specify
+a list of test cases to be processed, as a comma separated list.
+Conversely, the `--exclude` option (short `-x`) can be used
+to specify a list of cases which are not being processed.
-Since this docker is very self-contained, there should be no need to do
-interactive management of the docker, but if you feel the need, you can read the
-General Docker Help section of the MathJaxFonts docker readme.
+Examples:
-That's it!
+ node dockers/Screenshotter/screenshotter.js -i Sqrt,SqrtRoot
+ dockers/Screenshotter/screenshotter.sh --exclude=GreekLetters
diff --git a/dockers/Screenshotter/screenshotter.js b/dockers/Screenshotter/screenshotter.js
@@ -0,0 +1,237 @@
+"use strict";
+
+var childProcess = require("child_process");
+var fs = require("fs");
+var path = require("path");
+var net = require("net");
+var selenium = require("selenium-webdriver");
+
+var data = require("../../test/screenshotter/ss_data.json");
+
+var dstDir = path.normalize(
+ path.join(__dirname, "..", "..", "test", "screenshotter", "images"));
+
+//////////////////////////////////////////////////////////////////////
+// Process command line arguments
+
+var opts = require("nomnom")
+ .option("browser", {
+ abbr: "b",
+ "default": "firefox",
+ help: "Name of the browser to use"
+ })
+ .option("container", {
+ abbr: "c",
+ type: "string",
+ help: "Name or ID of a running docker container to contact"
+ })
+ .option("seleniumURL", {
+ full: "selenium-url",
+ help: "Full URL of the Selenium web driver"
+ })
+ .option("seleniumIP", {
+ full: "selenium-ip",
+ help: "IP address of the Selenium web driver"
+ })
+ .option("seleniumPort", {
+ full: "selenium-port",
+ "default": 4444,
+ help: "Port number of the Selenium web driver"
+ })
+ .option("katexURL", {
+ full: "katex-url",
+ help: "Full URL of the KaTeX development server"
+ })
+ .option("katexIP", {
+ full: "katex-ip",
+ "default": "localhost",
+ help: "Full URL of the KaTeX development server"
+ })
+ .option("katexPort", {
+ full: "katex-port",
+ "default": 7936,
+ help: "Port number of the KaTeX development server"
+ })
+ .option("include", {
+ abbr: "i",
+ help: "Comma-separated list of test cases to process"
+ })
+ .option("exclude", {
+ abbr: "x",
+ help: "Comma-separated list of test cases to exclude"
+ })
+ .parse();
+
+var listOfCases;
+if (opts.include) {
+ listOfCases = opts.include.split(",");
+} else {
+ listOfCases = Object.keys(data);
+}
+if (opts.exclude) {
+ var exclude = opts.exclude.split(",");
+ listOfCases = listOfCases.filter(function(key) {
+ return exclude.indexOf(key) === -1;
+ });
+}
+
+var seleniumURL = opts.seleniumURL;
+var katexURL = opts.katexURL;
+var seleniumIP = opts.seleniumIP;
+var seleniumPort = opts.seleniumPort;
+var katexIP = opts.katexIP;
+
+//////////////////////////////////////////////////////////////////////
+// Work out connection to selenium docker container
+
+function check(err) {
+ if (!err) {
+ return;
+ }
+ console.error(err);
+ console.error(err.stack);
+ process.exit(1);
+}
+
+function dockerCmd() {
+ var args = Array.prototype.slice.call(arguments);
+ return childProcess.execFileSync(
+ "docker", args, { encoding: "utf-8" }).replace(/\n$/, "");
+}
+
+if (!seleniumURL && opts.container) {
+ try {
+ // When using boot2docker, seleniumIP and katexIP are distinct.
+ seleniumIP = childProcess.execFileSync(
+ "boot2docker", ["ip"], { encoding: "utf-8" }).replace(/\n$/, "");
+ var config = childProcess.execFileSync(
+ "boot2docker", ["config"], { encoding: "utf-8" });
+ config = (/^HostIP = "(.*)"$/m).exec(config);
+ if (!config) {
+ console.error("Failed to find HostIP");
+ process.exit(2);
+ }
+ katexIP = config[1];
+ } catch(e) {
+ seleniumIP = katexIP = dockerCmd(
+ "inspect", "-f", "{{.NetworkSettings.Gateway}}", opts.container);
+ }
+ seleniumPort = dockerCmd("port", opts.container, seleniumPort);
+ seleniumPort = seleniumPort.replace(/^.*:/, "");
+}
+if (!seleniumURL && seleniumIP) {
+ seleniumURL = "http://" + seleniumIP + ":" + seleniumPort + "/wd/hub";
+}
+if (seleniumURL) {
+ console.log("Selenium driver at " + seleniumURL);
+} else {
+ console.log("Selenium driver in local session");
+}
+
+if (!katexURL) {
+ katexURL = "http://" + katexIP + ":" + opts.katexPort + "/";
+}
+var toStrip = "http://localhost:7936/"; // remove this from testcase URLs
+
+//////////////////////////////////////////////////////////////////////
+// Wait for container to become ready
+
+var attempts = 0;
+process.nextTick(seleniumIP ? tryConnect : buildDriver);
+function tryConnect() {
+ var sock = net.connect({
+ host: seleniumIP,
+ port: +seleniumPort
+ });
+ sock.on("connect", function() {
+ sock.end();
+ attempts = 0;
+ setTimeout(buildDriver, 0);
+ }).on("error", function() {
+ if (++attempts > 50) {
+ throw new Error("Failed to connect selenium server.");
+ }
+ setTimeout(tryConnect, 200);
+ });
+}
+
+//////////////////////////////////////////////////////////////////////
+// Build the web driver
+
+var driver;
+function buildDriver() {
+ var builder = new selenium.Builder().forBrowser(opts.browser);
+ if (seleniumURL) {
+ builder.usingServer(seleniumURL);
+ }
+ driver = builder.build();
+ setSize(targetW, targetH);
+}
+
+//////////////////////////////////////////////////////////////////////
+// Set the screen size
+
+var targetW = 1024, targetH = 768;
+function setSize(reqW, reqH) {
+ return driver.manage().window().setSize(reqW, reqH).then(function() {
+ return driver.takeScreenshot();
+ }).then(function(img) {
+ img = imageDimensions(img);
+ var actualW = img.width;
+ var actualH = img.height;
+ if (actualW === targetW && actualH === targetH) {
+ process.nextTick(takeScreenshots);
+ return;
+ }
+ if (++attempts > 5) {
+ throw new Error("Failed to set window size correctly.");
+ }
+ return setSize(targetW + reqW - actualW, targetH + reqH - actualH);
+ }, check);
+}
+
+function imageDimensions(img) {
+ var buf = new Buffer(img, "base64");
+ return {
+ buf: buf,
+ width: buf.readUInt32BE(16),
+ height: buf.readUInt32BE(20)
+ };
+}
+
+//////////////////////////////////////////////////////////////////////
+// Take the screenshots
+
+function takeScreenshots() {
+ listOfCases.forEach(takeScreenshot);
+}
+
+function takeScreenshot(key) {
+ var url = data[key];
+ if (!url) {
+ console.error("Test case " + key + " not known!");
+ return;
+ }
+ url = katexURL + url.substr(toStrip.length);
+ driver.get(url);
+ driver.takeScreenshot().then(function haveScreenshot(img) {
+ img = imageDimensions(img);
+ if (img.width !== targetW || img.height !== targetH) {
+ throw new Error("Excpected " + targetW + " x " + targetH +
+ ", got " + img.width + "x" + img.height);
+ }
+ if (key === "Lap" && opts.browser === "firefox" &&
+ img.buf[0x32] === 0xf8) {
+ /* There is some strange non-determinism with this case,
+ * causing slight vertical shifts. The first difference
+ * is at offset 0x32, where one file has byte 0xf8 and
+ * the other has something else. By using a different
+ * output file name for one of these cases, we accept both.
+ */
+ key += "_alt";
+ }
+ var file = path.join(dstDir, key + "-" + opts.browser + ".png");
+ fs.writeFile(file, img.buf, check);
+ console.log(key);
+ }, check);
+}
diff --git a/dockers/Screenshotter/screenshotter.py b/dockers/Screenshotter/screenshotter.py
@@ -1,107 +0,0 @@
-#!/usr/bin/env python2
-
-import argparse
-import json
-import os
-import png
-import StringIO
-import sys
-
-from selenium import webdriver
-
-
-def get_png_size(png_data):
- w, h, _, _ = png.Reader(file=StringIO.StringIO(png_data)).read()
- return (w, h)
-
-
-def set_driver_size(driver, width, height):
- """Correctly sets the size of the driver window so screenshots end up the
- provided size"""
- driver.set_window_size(width, height)
-
- screenshot_size = get_png_size(driver.get_screenshot_as_png())
- attempts = 0
- while (width, height) != screenshot_size:
- attempts += 1
- if attempts > 5:
- print "Tried 5 times to size screen correctly, bailing out"
- exit(1)
-
- ss_width, ss_height = screenshot_size
- driver.set_window_size(
- width + (width - ss_width),
- height + (height - ss_height))
- screenshot_size = get_png_size(driver.get_screenshot_as_png())
-
-
-def main():
- parser = argparse.ArgumentParser(
- description='Take screenshots of webpages', add_help=False)
- parser.add_argument('file', metavar='file.json')
- parser.add_argument('-t', '--tests', metavar='test', nargs='*')
- parser.add_argument('-w', '--width', metavar='width', default=1024,
- type=int)
- parser.add_argument('-h', '--height', metavar='height', default=768,
- type=int)
- parser.add_argument('-b', '--browser', metavar='browser',
- choices=['firefox'], default='firefox')
-
- args = parser.parse_args()
-
- data = None
- with open(args.file) as f:
- try:
- data = json.load(f)
- except ValueError:
- print "Invalid json in input file:", args.file
- exit(1)
-
- tests = []
-
- if args.tests is None:
- tests = data.keys()
- else:
- data_tests = data.keys()
- for test in args.tests:
- if test not in data_tests:
- print "Unknown test:", test
- exit(1)
-
- tests = args.tests
-
- print "Starting up"
- sys.stdout.flush()
-
- driver = None
- if args.browser == 'firefox':
- driver = webdriver.Firefox()
- else:
- print "Unknown browser:", args.browser
- exit(1)
-
- set_driver_size(driver, args.width, args.height)
-
- data_dir = os.path.join(
- os.path.dirname(os.path.realpath(args.file)), "images")
-
- try:
- os.mkdir(data_dir)
- except OSError:
- pass
-
- for test, url in data.iteritems():
- if test in tests:
- filename = os.path.join(
- data_dir, '%s-%s.png' % (test, args.browser))
-
- print "Running:", test
- sys.stdout.flush()
-
- driver.get(url)
- driver.get_screenshot_as_file(filename)
-
- print "Done"
-
-if __name__ == '__main__':
- main()
diff --git a/dockers/Screenshotter/screenshotter.sh b/dockers/Screenshotter/screenshotter.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# This script does a one-shot creation of screenshots, creating needed
+# docker containers and removing them afterwards. During development,
+# it might be desirable to avoid the overhead for starting and
+# stopping the containers. Developers are encouraged to manage
+# suitable containers themselves, calling the screenshotter.js script
+# directly.
+
+status=0
+for browserTag in firefox:2.46.0; do
+ browser=${browserTag%:*}
+ image=selenium/standalone-${browserTag}
+ echo "Starting container for ${image}"
+ container=$(docker run -d -P ${image})
+ [[ ${container} ]] || continue
+ echo "Container ${container:0:12} started, creating screenshots..."
+ if node "$(dirname "$0")"/screenshotter.js \
+ --browser="${browser}" --container="${container}" "$@"; then
+ res=Done
+ else
+ res=Failed
+ status=1
+ fi
+ echo "${res} taking screenshots, stopping and removing ${container:0:12}"
+ docker stop ${container} >/dev/null && docker rm ${container} >/dev/null
+done
+exit ${status}
diff --git a/package.json b/package.json
@@ -20,6 +20,8 @@
"jasmine-node": "2.0.0-beta4",
"jshint": "^2.5.6",
"less": "~1.7.5",
+ "selenium-webdriver": "^2.46.1",
+ "nomnom": "^1.8.1",
"uglify-js": "~2.4.15"
},
"bin": "cli.js",
diff --git a/test/screenshotter/images/Lap_alt-firefox.png b/test/screenshotter/images/Lap_alt-firefox.png
Binary files differ.
diff --git a/test/screenshotter/test.html b/test/screenshotter/test.html
@@ -8,6 +8,9 @@
#math, #pre, #post {
font-size: 4em;
}
+ body {
+ font-family: "DejaVu Serif",serif;
+ }
</style>
</head>
<body>
