DSL to notate specification, rather than test framework.

jingoh

# JINGOH 3.0.1
*NOTE!* Jingoh is very personal products, so use your own risk.
Other products (if any) are strongly recommended.

## What is this?
DSL to notate specification, rather than test framework.

## Notable differences from other test suites.

### Specification notation rather than test framework.
When specification is modified, test should be fixed.
Vice vaca, when a hole found in specification via test, specification should be fixed.
Idealy, both specification and test should be managed in one place.

### Readability oriented syntax rather than writablility.
In concept above, test is specification, so readability prior than writability.
Author may need writability.
Unfortunately, author is few, but the third persons.
For syntax details, see [SYNTAX.md](SYNTAX.md).

### Including specification template (i.e. as test template).
TDD begginer may not understand what should be written as test.
Thanks to CLHS, we know what should be written as specification.
For details, see [generator/README.md](generator/README.md).

### Including dribble for REPL driven development.
Most CLer will do REPL driven development.
Writting tiny codes, loading it to lisp environment, then checking it inside REPL.
If find something unexpected behavior, fixing codes, reloading it and so on.
For such users, jingoh provides special dribble repl.
Your interactions with REPL are automatically send spec file.
For details, see [generator/README.md](generator/README.md).

### Including from-spec(i.e. test)-file-to-HTML converter.
Managing both test and specification at one place allows you to never write documentation, since it is already written.
You can say "See spec/test file.", but we provide little bit prittier to html comverter.
For details, see [documentizer/README.md](documentizer/README.md).

### Including from-spec(i.e. test)-file-to-github-wiki converter.
Additionaly, we provide to github-wiki converter.
For details, see [documentizer/README.md](documentizer/README.md).

### Including from-spec(i.e. test)-file-to-lisp-documentation importer.
Additionaly, we provide lisp documentation importer.
You can refer spec documentation via CL:DOCUMENTATION.
For details, see [documentizer/README.md](documentizer/README.md).

### Customizable issue printer.
What is the best issue report?
It is issue of flavor.
We print issue as raw data object.
Thanks to CLOS, you can easily customize printer with `PRINT-OBJECT`.

### Support coloring printing.
For readability, we provide coloring printing.
In many cases, you will not feel like to customize issue printer.

### Support S-Expression-equal. (alpha quality.)
It is hard to test macro generate correct S-Expression.
Because, there is symbol which generate via `GENSYM`.
We will provide `SEXP=`. (This is alpha quality, so it is internal.)

### Support parallel testing.
Optionaly you can choose parallel testing.

### Including project skelton generator.
Battery included.
You can ignore some annoying knowledge about backward.

## How to use.
### Initialization
If your system is already made, evaluate below.

*NOTE!* You must specify your system with *keyword*.

```lisp
(asdf:load-system :jingoh.generator)
(jingoh.generator:generate :your-system)
```
In this case, jingoh will make `spec` subdirectory in your system source directory like below.

```
your-system/
  |--- your-system.asd
  |--- your-system.lisp
  |--- spec/
        |--- your-system.test.asd
        |--- your-system.lisp
```

Else if your system is not made yet, specify `:init` keyword with T.

```lisp
(jingoh.generator:generate :your-system :init t)
```
In this case, jingoh works like project skeleton generator (e.g. quick-project.).

```
your-system/
  |--- README.md
  |--- spec/
        |--- your-system.lisp
        |--- your-system.test.asd
  |--- src/
        |--- your-system.lisp
  |--- your-system.asd
```
In both cases, test is already setup.
To run test, evaluate like below.

```lisp
(asdf:test-system :your-system)
```

### Writing specifications.
Let's say your-system has function like below.

```lisp
(defun adder (num)
  "Make adder function."
  (lambda (x)
    (+ x num)))
```
To add specification of ADDER to your spec file, evaluate like below.

```lisp
(jingoh.generator:dribble :your-system)

DRIBBLE>
```
Now, you are in the dribble repl.
To append spec file with template, input :g.

```lisp
DRIBBLE> :g

>>
```

Input function name.

```
>> adder

DRIBBLE>
```
Jingoh appends spec file with template like below.

```
(requirements-about ADDER)

;;;; Description:
; Make adder function.

#+syntax
(ADDER num) ; => result

;;;; Arguments and Values:

; num := 

; result := 

;;;; Affected By:

;;;; Side-Effects:

;;;; Notes:

;;;; Exceptional-Situations:

```
This template is designed to be same with hyper-spec.

Different from ordinary repl, dribble repl ask you each result are expected.

```lisp
DRRIBLE> (adder 1)

FUNCTION
Is it expected return type? (y or n)
```

If yes, spec file are appended.

```lisp
Is it expected return type? (y or n) y

#<CLOSURE (LAMBDA (X) :IN ADDER) {12345}>
DRIBBLE>
```

Ok, try to next test.

```lisp
DRIBBLE> (adder :not-number)

FUNCTION
Is it expected return type? (y or n)
```

Let's say you want to specify signaling an error in this case.
FUNCTION is not expected return type.

When you choice NO, it invokes ordinary deubgger.

```lisp
Is it expected return type? (y or n) n

debugger invoked on a UNEXPECTED-BEHAVIOR in thread
#<THREAD ....>:

restarts (invokable by number or by possibly-abbreviated name):
  0: [USE-VALUE] Specify expected type.
  1: [DRIBBLE  ] Return to dribble.
  2: [ABORT    ] Exit debugger, returning to top level.
```

This is ordinary debugger, so you can do anything in debugger, editting, reloading, etc.

Let's modify source like below.

```lisp
(defun adder (num)
  "Make adder function."
  (check-type num number)
  (lambda (x)
    (+ x num)))
```

After modifying and reloading your system in the debugger, select restart `DRIBBLE` to return dribble repl.

```lisp
DRIBBLE> (adder :not-number)

debugger invoded on a SIMPLE-TYPE-ERROR in thread
#<THREAD ...>:

restarts (invokable by number or by possibly-abbreviated name):
  0: [STORE-VALUE] Supply a new value for NUM.
  1: [APPEND-SPEC] Append spec, returning to dribble.
  2: [DRIBBLE    ] Return to dribble.
  3: [ABORT      ] Exit debugger, returning to top level.
```

Ok, signaling an error is expected behavior.
Let's choice restart `APPEND-SPEC`.

To exit dribble repl, input :q.

```lisp
DRIBBLE> :q

*
```

After dribble session, edit the spec file to move test code in the right place.

After editting, spec file may like below.
To write comment, use markdown syntax with semicolon escape.
To know completed syntax, see [SYNTAX.md](SYNTAX.md).
One-sentence-some-examples style is recommended.

```lisp
(requirements-about ADDER)

;;;; Description:
; Make adder function.
#?(ADDER 1) :be-the FUNCTION

; Apply number to returned function, such function return added value.
#?(FUNCALL (ADDER 1) 2) => 3

#+syntax
(ADDER num) ; => result

;;;; Arguments and Values:

; num := number which is acceptable for `CL:+`, otherwise error
#?(ADDER :NOT-NUMBER) :signals SIMPLE-TYPE-ERROR

; result := function as `(FUNCTION (NUMBER) NUMBER)`

;;;; Affected By:
; none

;;;; Side-Effects:
; none

;;;; Notes:

;;;; Exceptional-Situations:
```

### Running test.
*NOTE!* Before running test, do not forget export (if it will be exported.) symbol from your system package, or import  (if it will be internals.) symbol from your system package to spec package.

```lisp
(asdf:test-system :your-system)
```

![passed example](./img/pass.png)

### Documentization
After writing your-system's spec file, if you want to get your system's html documentations, evaluate like below.

```lisp
(asdf:load-system :jingoh.documentizer)
(jingoh.documentizer:documentize :your-system)
```
Jingoh will make `doc` subdirectory in your system source directory.

If you want provide such documentations as github wiki, after clone github wiki repository, evaluate like below.

```lisp
(jingoh.documentaizer:github :your-system "path/to/your-system.wiki/")
```
Then push it.

### Parallel testing.
Normally, jingoh run tests sequentially.
If you want to run tests in parallel, modify `spec/your-system.test.asd` like below.

```lisp
(defsystem :your-system.test
  :depends-on (:jingoh.parallel ; <--- instead of :jingoh
               "your-system")
  :components ((:file "your-system"))
  :perform
  (test-op(o c)(symbol-call :jingoh.parallel ; <--- instead of :jingoh
                            :pexamine ; <--- instead of :examine
                            :your-system)))
```
*NOTE!* Parallelizing has its own overhead, so parallel testing may slower than sequential testing.
## From developer

### Product's goal
?
### License
MIT
### Tested with
* SBCL/2.2.4
* CCL/1.12.1
* CLISP/2.49 ; See [generator].
* ECL/21.2.1
* Allegro/10.1
* CMUCL/21D ; See [tester].
* ABCL/1.9.0 ; See [generator], [documentizer] and/or [tester].

[generator]: generator/README.md#known-issue
[tester]: tester/README.md#known-issue
[documentizer]: documentizer/README.md#known-issue

### Known issue.

## Installation
TODO


jingoh.examiner

jingoh.org

jingoh.reader

jingoh.tester

named-readtables

## Abstract concepts
Jingoh provides the features to notate specification, rather than test framework.
Once you writes your library's specifications with jingoh, such file works as test.
Additionaly, it will be enough to be used as tutolials for end users.

## Packages
Package JINGOH responds to be as interface.
JINGOH's external symbols are main features for light users.
JINGOH's internal symbols are inherited from other modules.

System (same as package) JINGOH.ORG, JINGOH.TESTER, JINGOH.EXAMINER, JINGOH.READER are modules.

## Extensions
Jingoh provides some extensions.

### Jingoh.generator
Provides the features to generate test template.

### Jingoh.documentizer
Provides the features to convert test file to html, or markdown for github wiki.

### Jingoh.parallel
Provides the feature to run test in parallel.

## NOTE
Jingoh compiles test form at run time.
Its advantage is recallability.
When test code is not modified but system source code,
you does not reload test file (i.e. does not need to evaluate ASDF:TEST-SYSTEM).
Just reload system then evaluate JINGOH:EXAMINE.
JINGOH:EXAMINE can control which test should be evaluated. (the default is all)

Disadvantage is higher running cost.



3bmd

3bmd-ext-code-blocks

asdf

cl-ppcre

eclector

read-as-string

uiop

Jingoh extension: Import/Convert specification documentation.

jingoh.documentizer

jingoh.documentizer.test

cl-ansi-text

Jingoh module for test running and control/config output.

# jingoh.examiner - Jingoh's printing issues feature.

## Abstract concepts
Jingoh.examiner provides features to examine implementation of requirements, and to print result.

For modulability, jingoh.examiner does not respond to register requirements or how to handle requirements.
It is jingoh.org or jingoh.tester responds, respectively.


jingoh.examiner.test

alexandria

closer-mop

cl-unification

lambda-fiddle

millet

prompt-for

trivial-cltl2

Jingoh extension: Project skelton and test template generator and more.

jingoh.generator

jingoh.generator.test

check-bnf

# jingoh.org - Jingoh's background database system

## Abstract concepts
Jingoh.org provides jingoh's background database system.
Provides abstract container type named ORG and its operators.

## Terms
### ORG
Stands in ORGanization.
It manages all REQUIREMENTs of SUBJECTs about your system.
You can refer it as test-suite which usual test framework has.

### REQUIREMENT
What the operator must/should/may behaves.
You can refer it as test which usual test framework has.

### SUBJECT
Target of REQUIREMENT.

## Management hierarchy
```
+-----+
| ORG | ; e.g. system or package
+-----+
   |
+----------------------------------------+
|+----------+    			 | ; called "specifications"
|| SUBJECTs | ; e.g. functions or macros |
|+----------+				 |
|   |					 |
|+--------------+			 |
|| REQUIREMENTS | ; i.e. behaviors       |
|+--------------+			 |
+----------------------------------------+
```


jingoh.org.test

bordeaux-threads

cl-cpus

lparallel

jingoh.parallel

jingoh.parallel.test

## Abstract concepts

Jingoh.reader provides dispatch macro function for jingoh.tester and named-readtables.

Dispatch macro `#?` allows you to write test form as if it is written in REPL.
It may be a worse way to write a test, but the written form will be better looking especially for a third person.

If you do not like using the dispatch macro, you can ignore this.


jingoh.reader.test

jingoh/test

cl-colors2

structure-ext

vivid-colors

vivid-diff

Jingoh module for issue objects and interface for jingoh.org.

# jingoh.tester - Dsl for requirement.

## Abstract concepts
Jingoh.tester is a dsl for requirement.
It provides -
* Notations of requirement.
* Testing feature which tests implementation satisfies requirement or not.
* Abstract data types which represents issues.

For extensibility, requirement's internal representation is not specified.
Although Jingoh.tester provides operators which handle requirements.
So users does not need to know about what happen behind the black box.

For modulability, jingoh.tester does not provide report functions, and restoring database system.
It is jingoh.examiner or jingoh.org who responds it respectively.

## Terms

### REQUIREMENT
REQUIREMENT is internal datatype which represents specifications of requirement for operator's behavior.

### ISSUE
ISSUE is abstract datatype which contains information about issue of implementation of requiements.



jingoh

Upstream URL

Author

License

jingoh

Version:

License:

Authors:

Dependencies:

jingoh.documentizer

Version:

License:

Authors:

Dependencies:

jingoh.documentizer.test

Version:

Dependencies:

jingoh.examiner

Version:

License:

Authors:

Dependencies:

jingoh.examiner.test

Version:

Dependencies:

jingoh.generator

Version:

License:

Authors:

Dependencies:

jingoh.generator.test

Version:

Dependencies:

jingoh.org

Version:

License:

Authors:

Dependencies:

jingoh.org.test

Version:

Dependencies:

jingoh.parallel

Version:

License:

Authors:

Dependencies:

jingoh.parallel.test

Dependencies:

jingoh.reader

Version:

License:

Authors:

Dependencies:

jingoh.reader.test

Version:

Dependencies:

jingoh/test

Dependencies:

jingoh.tester

Version:

License:

Authors:

Dependencies:

jingoh.tester.test

Version:

Dependencies:

Dependencies (23)

Dependents (16)