[nongnu] elpa/buttercup e7e51a6e2a 6/6: Merge branch 'docs/eask'

[ELPA Syncer]

branch: elpa/buttercup
commit e7e51a6e2a4e6e0e9935299d4366395403cd04e3
Merge: c6693d3667 457b6525ed
Author: Ola Nilsson <ola.nilsson@gmail.com>
Commit: Ola Nilsson <ola.nilsson@gmail.com>

    Merge branch 'docs/eask'
    
    * docs/eask:
      Update language identifiers of running-tests.md
      docs(exec): Document use with Eask
---
 docs/running-tests.md | 141 ++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 125 insertions(+), 16 deletions(-)

diff --git a/docs/running-tests.md b/docs/running-tests.md
index 4ce580d606..09c86f3842 100644
--- a/docs/running-tests.md
+++ b/docs/running-tests.md
@@ -30,7 +30,7 @@ feature/feature.el
 
 **feature.el**
 
-```Emacs-Lisp
+```elisp
 (defun featurize (bug feature)
   (format "It's not a %s, it's a %s" bug feature))
 
@@ -39,7 +39,7 @@ feature/feature.el
 
 **Cask**
 
-```
+```elisp
 (source gnu)
 (source melpa-stable)
 
@@ -49,7 +49,7 @@ feature/feature.el
 
 **tests/test-feature.el**
 
-```Lisp
+```elisp
 (require 'feature)
 
 (describe "The feature"
@@ -66,7 +66,7 @@ You can now use Cask to run your tests.
 First, you have to install the dependencies. You only have to do this
 once, or when the dependencies change:
 
-```
+```console
 $ cask
 Extracting buttercup-1.1/
 Extracting buttercup-1.1/buttercup-compat.el
@@ -84,7 +84,7 @@ Generating autoloads for buttercup.el...done
 
 Now, you can run your tests:
 
-```
+```console
 $ cask exec buttercup -L .
 Running 1 specs.
 
@@ -137,7 +137,7 @@ testing: Eldev will determine that on-the-fly.
 
 To run your test, just execute:
 
-````
+```console
 $ eldev test
 [1/1] Installing package ‘buttercup’ (1.23) from ‘melpa-stable’...
 Running 1 specs.
@@ -146,32 +146,133 @@ The feature
   can use bug and feature (2.58ms)
 
 Ran 1 specs, 0 failed, in 2.68ms.
-````
+```
 
 You can also specify patterns on the command line, to avoid running
 all the tests at once, i.e.:
 
-````
+```console
 $ eldev test foo
-````
+```
 
 If you have several test files, you can avoid running all the tests by
 specifying filename after `-f` (`--file`) option:
 
-````
+```console
 $ eldev test -f main.el
-````
+```
 
 For more information, please see tool’s own documentation, especially
 [the section about testing](https://github.com/doublep/eldev#testing).
 
+## Eask
+> 📢 Eask is very similar to Cask; anything that applies to Cask will apply to 
Eask
+
+[Eask](https://github.com/emacs-eask/cli) is a replacement for Cask which is
+actively maintained.
+
+### Project Directory Layout
+
+> 📢 The project directory layout is similar to the Cask's one. But instead of
+> `Cask`-file, you should have `Eask`-file as a replacement.
+
+A basic project layout requires a project file, called `feature.el`
+here, an `Eask`-file to define dependencies, and a `tests/` directory
+for tests. It should look roughly like this:
+
+```
+feature/feature.el
+        Eask
+        tests/test-feature.el
+```
+
+**feature.el**
+
+```elisp
+(defun featurize (bug feature)
+  (format "It's not a %s, it's a %s" bug feature))
+
+(provide 'feature)
+```
+
+**Eask-file**
+
+```elisp
+(source 'gnu)
+(source 'melpa-stable)
+
+(development
+ (depends-on "buttercup"))
+```
+
+**tests/test-feature.el**
+
+```elisp
+(require 'feature)
+
+(describe "The feature"
+  (it "can use bug and feature"
+    (expect (featurize "bug" "feature")
+            :to-equal
+            "It's not a bug, it's a feature")))
+```
+
+### Running Tests
+
+You can now use Eask to run your tests.
+
+First, you have to install the dependencies. You only have to do this once, or
+when the dependencies change:
+
+```console
+$ eask install-deps --dev
+...
+
+Installing 1 development dependency...
+Loading package information... done
+  - Installing buttercup (20230119.2337)... done
+(Total of 1 dependency installed, 0 skipped)
+```
+
+Now, you can run your tests:
+
+```console
+$ eask exec buttercup -L .
+...
+
+Running 1 specs.
+
+The feature
+  can use bug and feature
+
+Ran 1 specs, 0 failed, in 0.0 seconds.
+```
+
+That’s it. Buttercup’s built-in discover test runner looks for files
+named `test-*.el`, `*-test.el` or `*-tests.el`.
+
+Use the `--pattern PATTERN` option to only Only run tests with names
+matching PATTERN. The `--pattern` option can be used multiple times,
+in which case tests will be run if they match any of the given
+patterns. Combine with the `--no-skip` option to filter out the
+skipped tests.
+
+You can run this command whichever way you like. Common choices
+include a Makefile or shell scripts.
+
+See [relevant documentation](https://emacs-eask.github.io/) on Eask's own page
+for more information.
+
 ## Projectile
 
-If you use [Projectile](https://github.com/bbatsov/projectile) for interacting 
with your projects you can set the "default" project test command to be 
available when you invoke `projectile-test-project`.  Create a `.dir-locals.el` 
file in the the root of your project tree (next to your Cask file).  An example:
+If you use [Projectile](https://github.com/bbatsov/projectile) for interacting
+with your projects you can set the "default" project test command to be
+available when you invoke `projectile-test-project`.  Create a `.dir-locals.el`
+file in the the root of your project tree (next to your Cask file).  An 
example:
 
 **.dir-locals.el**
 
-```
+```elisp
 ((nil . ((eval . (progn
                    (require 'projectile)
                    (puthash (projectile-project-root)
@@ -184,12 +285,14 @@ testing command on its own, so you don’t need any special 
steps.
 
 ## Travis
 
+### Cask
+
 If your project is hosted on github, you can use
 [Travis CI](https://travis-ci.org/) as your continuous integration
 environment. Buttercup can easily be used in such a setup. Simply add
 the following `.travis.yml` file:
 
-```
+```yaml
 language: emacs-lisp
 sudo: false
 cache: apt
@@ -211,9 +314,11 @@ Most of the complexity here is from installing
 [EVM](https://github.com/rejeep/evm) and Cask to be able to test your
 project using different Emacs versions.
 
+### Eldev
+
 For Eldev, use the following `.travis.yml` file:
 
-````
+```yaml
 language: emacs-lisp
 dist: trusty
 
@@ -227,6 +332,10 @@ install:
 
 script:
   - eldev -p -dtT test
-````
+```
 
 For details, see [tool’s own 
documentation](https://github.com/doublep/eldev#continuous-integration).
+
+### Eask
+
+For Eask, please see [tool's 
documentation](https://emacs-eask.github.io/Continuous-Integration/Travis-CI/).