Update remaining docs

docs/source/how-to-guides/broken-links.rst

@@ -4,11 +4,11 @@ Broken Links
 This is simple specification used for finding broken internal links. External
 links are not followed. It's based on Domen Kožar's gist. [#original]_
 
-.. literalinclude:: BrokenLinks.spec.purs
-   :language: haskell
+.. literalinclude:: broken-links.strom
+   :language: javascript
 
 
-Tweak the patterns and the precicate to fit your use case. You might not have
-status codes rendered, but texts like "Page not found".
+Tweak the patterns and the predicate to fit your use case. You might not have
+status codes rendered, but texts like "Page not found" or "Access denied".
 
-.. [#original] Domen Kožar wrote the original specification for `Cachix <https://cachix.org>`__ and published it along with a GitHub Actions setup: https://gist.github.com/domenkozar/71135bf7aa6d50d6911fb74f4dcb4bad
+.. [#original] Domen Kožar wrote the original specification for `Cachix <https://cachix.org>`__ using one of the first versions of Quickstrom, and published it along with a GitHub Actions setup: https://gist.github.com/domenkozar/71135bf7aa6d50d6911fb74f4dcb4bad

docs/source/how-to-guides/broken-links.strom

@@ -0,0 +1,35 @@
+import quickstrom;
+
+// Only links beginning with a slash and ending
+// with .html are followed. We could also use
+// an absolute base URL, e.g:
+//
+//     a[href^='https://example.com']
+//
+action ~navigate! =
+  click!(`a[href^='/'][href$='.html']`);
+
+// We're interested in finding links that lead
+// to pages rendered with these status codes in
+// the heading.
+let patterns = [ "404", "500" ];
+
+// In our system's error pages, status codes
+// are rendered in an <h1> element.
+let ~heading =
+  let h1 = first(`h1`);
+  h1.textContent when h1 != null;
+
+// Check if the heading has any of the error
+// codes in the text.
+let ~hasErrorCode = 
+  exists p in patterns {
+    contains(p, heading)
+  };
+
+// This is the safety property. At no point,
+// following only internal links, should we
+// see error codes.
+let ~proposition = always (not hasErrorCode);
+
+check proposition with * when loaded?;

docs/source/how-to-guides/testing-in-github-actions.rst

@@ -20,20 +20,23 @@ commit to the ``main`` branch. It's based on Domen Kožar's gist. [#original]_
 
        # We use `install-nix-action` and `cachix-action` to quickly install the 
        # latest Quickstrom from a binary cache.
-       - uses: cachix/install-nix-action@v12
-       - uses: cachix/cachix-action@v8
+       - uses: cachix/install-nix-action@v18
+       - uses: cachix/cachix-action@v12
          with:
            name: quickstrom
        - run: nix-env -iA quickstrom -f https://github.com/quickstrom/quickstrom/tarball/main
 
-       # We install and run Geckodriver in the background, so that we can run
-       # tests using Firefox.
-       - run: nix-env -i geckodriver -f https://github.com/NixOS/nixpkgs/tarball/nixos-21.05
-       - run: geckodriver&
+       # Now, run tests! This assumes there's a file called 
+       # `example.strom` in the root of the GitHub repository.
+       - run: quickstrom check example https://example.com --reporter=html --html-report-directory=report
 
-       # Finally, run tests! This assumes there's a file called 
-       # `example.spec.purs` in the root of the GitHub repository.
-       - run: quickstrom check example.spec.purs https://example.com
+       # Finally, we archive HTML report as an artifact. This
+       # can be downloaded an inspected after failed checks.
+       - name: Archive test results
+         uses: actions/upload-artifact@v3
+         with:
+           name: test-report
+           path: report
 
 Replace the placeholder paths and URLs. 
 
@@ -43,4 +46,4 @@ Next Steps
 * You might want to run tests in Chrome instead. See :doc:`../topics/checking` for instructions on using other browsers.
 * If you'd like to check multiple specs and in multiple browsers, see `matrix configurations <https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix>`_ in the GitHub Actions documentation.
 
-.. [#original] Domen Kožar wrote the original GitHub Action configuration for `Cachix <https://cachix.org>`__: https://gist.github.com/domenkozar/71135bf7aa6d50d6911fb74f4dcb4bad
+.. [#original] Domen Kožar wrote the original GitHub Action configuration for `Cachix <https://cachix.org>`__: https://gist.github.com/domenkozar/71135bf7aa6d50d6911fb74f4dcb4bad

docs/source/installation/docker.rst

@@ -6,41 +6,42 @@ the image using Docker:
 
 .. code-block:: console
 
-   $ docker pull quickstrom/quickstrom:latest
+   $ docker pull quickstrom/quickstrom:0.5.0
 
 Verify that Quickstrom can now be run using Docker:
 
 .. code-block:: console
 
-   $ docker run quickstrom/quickstrom:latest quickstrom version
+   $ docker run quickstrom/quickstrom:0.5.0 \
+       quickstrom --help
 
-You can now run Quickstrom with ``docker run``:
+You can now run Quickstrom checks:
 
 .. code-block:: console
    :linenos:
 
    $ docker run \
-     --mount=type=bind,source=$PWD/specs,target=/specs \
-     quickstrom/quickstrom:latest \
+     -v $PWD/specs:/specs \
+     quickstrom/quickstrom:0.5.0 \
      quickstrom -I/specs \
      check example \
      https://example.com
 
-There's a lot of things going in the above session. Let's look at what each
+There's a lot of things going in the above command. Let's look at what each
 line does:
 
 #. Uses `docker run` to execute a program inside the container
 #. Mounts a host directory containing specification(s) to ``/specs`` in the container filesystem
-#. Uses the image ``quickstrom/quickstrom`` with the ``latest`` target
+#. Uses the image ``quickstrom/quickstrom`` with the ``0.5.0`` tag
 #. Runs ``quickstrom`` with the mounted ``/specs`` directory as an include path
 #. Checks the ``example`` specificiation module (i.e. ``/specs/example.strom``)
-#. Passes an origin URI (this could also be a file path in the mounted directory)
+#. Passes an origin URI (this could also be a file path into the mounted directory)
 
 Accessing a Server on the Host
 ==============================
 
 If you wish to run Quickstrom in Docker and test a website being
-hosted by the Docker host system you can set the url to ``localhost``
+hosted by the Docker host system you can set the URL to ``localhost``
 (or ``host.docker.internal`` for MacOS).
 
 
@@ -49,7 +50,7 @@ hosted by the Docker host system you can set the url to ``localhost``
 
    $ docker run \
      --network=host \
-     --mount=type=bind,source=$PWD/specs,target=/specs \
+     -v $PWD/specs:/specs \
      quickstrom/quickstrom:latest \
      quickstrom -I/specs \
      check example \

docs/source/installation/nix.rst

@@ -22,9 +22,8 @@ executable:
 
 If you're on Darwin, you're probably going to have problems with
 Firefox and Chrome from nixpkgs. You can exclude browsers from the
-Quickstrom environment and provide them on your own, but there's often
-problems with version mismatches between chromedriver and
-Chrome/Chromium. If you want to do this, override it with this command:
+Quickstrom environment and provide them on your own, e.g. through
+Homebrew. If you want to do this, override it with this command:
 
 .. code-block:: console
 

docs/source/topics/checking.rst

@@ -37,3 +37,13 @@ running the ``check`` command:
    $ quickstrom check \
       --browser=chrome \
       ... # more options
+
+
+You can also override which binary it uses when launching the browser:
+
+.. code-block:: console
+
+   $ quickstrom check \
+      --browser=chrome \
+      --browser-binary=/usr/bin/google-chrome-stable \
+      ... # more options

docs/source/topics/reporters.rst

@@ -30,13 +30,10 @@ showing screenshots and overlayed state information for the queried elements.
 To set the directory to generate the report in, use the option
 ``--html-report-directory=<DIR>``.
 
-The HTML report directory must be served through an HTTP server in order
-to avoid problems with CORS. If you have Python 3 installed, serve it with
-the following command:
+.. tip::
 
-.. code-block:: console
-
-   $ python3 -m http.server -d <DIR>
+   If you run Quickstrom using Docker, make sure to generate the HTML
+   report in a mounted directory so that you can access it from the host.
 
 JSON
 ----
@@ -46,4 +43,4 @@ JSON file and screenshots, no HTML files. In the report directory you'll find
 a file ``report.json`` that you can work with.
 
 To set the directory to generate the report in, use the option
-``--json-report-directory=<DIR>``.
+``--json-report-directory=<DIR>``.

docs/source/topics/troubleshooting.rst

@@ -13,9 +13,6 @@ enable debug logs:
 
 Also, the underlying Specstrom interpreter outputs its log file in the
 current working directory, called ``interpreter.log``. Its location
-can be changed using the ``--interpreter-log-file`` option.
+can be changed using the ``--interpreter-log-file=...`` option.
 
-If you have any syntactic errors or any runtime errors occur when
-evaluating the specification, you'll find those in the interpreter
-log. In the future, however, we want them to be printed directly by
-Quickstrom.
+Finally, the Webdriver log can be stored by specifying ``--driver-log-file=...``.