From 509868fbd214c7f4e4f1ec299bbc2f40d8361a48 Mon Sep 17 00:00:00 2001 From: Bot Date: Sun, 7 Jan 2024 05:44:57 +0000 Subject: [PATCH] DOCS : Regenerated docs. --- README.md | 7 +- docs/public/index.md | 7 +- docs/public/using/engine/index.md | 1 + docs/public/using/engine/rewrite-given.md | 108 ++++++++++++++++++++++ docs/public/why-not/gherkin.md | 2 +- 5 files changed, 118 insertions(+), 7 deletions(-) create mode 100644 docs/public/using/engine/rewrite-given.md diff --git a/README.md b/README.md index 096dc651..db083ff0 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,9 @@ Type-safe [StrictYAML](https://hitchdev.com/hitchstory/why/strictyaml) integrati Project | Storytests | Python code | Doc template | Autogenerated docs ---|---|---|---|--- -[Website](https://github.com/hitchdev/hitchstory/tree/master/examples/website) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/website/tests/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/website/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docs/correct-my-spelling.md) -[REST API](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/restapi/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docs/correct-my-spelling.md) -[Interactive command line app](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/tests/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/tests/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/commandline/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/docs/correct-my-spelling.md) +[Website](https://github.com/hitchdev/hitchstory/tree/master/examples/website) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/correct-my-spelling.story) | [engine.py](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/engine.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/website/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docs/correct-my-spelling.md) +[REST API](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/correct-my-spelling.story) | [engine.py](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/engine.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/restapi/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docs/correct-my-spelling.md) +[Interactive command line app](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/engine.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/tests/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/commandline/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/docs/correct-my-spelling.md) [A Python API](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/tests/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/tests/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/pythonapi/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/docs/correct-my-spelling.md) @@ -248,6 +248,7 @@ How to use the different features of the story engine: - [Match two strings and show diff on failure](https://hitchdev.com/hitchstory/using/engine/match-two-strings) - [Extra story metadata - e.g. adding JIRA ticket numbers to stories](https://hitchdev.com/hitchstory/using/engine/metadata) - [Story with parameters](https://hitchdev.com/hitchstory/using/engine/parameterized-stories) +- [Story that rewrites given preconditions](https://hitchdev.com/hitchstory/using/engine/rewrite-given) - [Story that rewrites itself](https://hitchdev.com/hitchstory/using/engine/rewrite-story) - [Story that rewrites the sub key of an argument](https://hitchdev.com/hitchstory/using/engine/rewrite-subkey-of-argument) - [Raising a Failure exception to conceal the stacktrace](https://hitchdev.com/hitchstory/using/engine/special-failure-exception) diff --git a/docs/public/index.md b/docs/public/index.md index 2868e50f..f0309131 100644 --- a/docs/public/index.md +++ b/docs/public/index.md @@ -21,9 +21,9 @@ Type-safe [StrictYAML](why/strictyaml) integration tests run from pytest. They c Project | Storytests | Python code | Doc template | Autogenerated docs ---|---|---|---|--- -[Website](https://github.com/hitchdev/hitchstory/tree/master/examples/website) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/website/tests/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/website/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docs/correct-my-spelling.md) -[REST API](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/restapi/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docs/correct-my-spelling.md) -[Interactive command line app](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/tests/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/tests/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/commandline/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/docs/correct-my-spelling.md) +[Website](https://github.com/hitchdev/hitchstory/tree/master/examples/website) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/story/correct-my-spelling.story) | [engine.py](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/engine.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/website/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/website/hitch/docs/correct-my-spelling.md) +[REST API](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/story/correct-my-spelling.story) | [engine.py](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/engine.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/restapi/hitch/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/restapi/hitch/docs/correct-my-spelling.md) +[Interactive command line app](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/hitch/engine.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/tests/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/commandline/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/commandline/docs/correct-my-spelling.md) [A Python API](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi) | [add todo](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/story/add-todo.story), [correct spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/story/correct-my-spelling.story) | [test_integration.py](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/tests/test_integration.py) | [docstory.yml](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/tests/docstory.yml) | [Add todo](https://github.com/hitchdev/hitchstory/blob/master/examples/pythonapi/docs/add-and-retrieve-todo.md), [Correct my spelling](https://github.com/hitchdev/hitchstory/tree/master/examples/pythonapi/docs/correct-my-spelling.md) @@ -252,6 +252,7 @@ How to use the different features of the story engine: - [Match two strings and show diff on failure](using/engine/match-two-strings) - [Extra story metadata - e.g. adding JIRA ticket numbers to stories](using/engine/metadata) - [Story with parameters](using/engine/parameterized-stories) +- [Story that rewrites given preconditions](using/engine/rewrite-given) - [Story that rewrites itself](using/engine/rewrite-story) - [Story that rewrites the sub key of an argument](using/engine/rewrite-subkey-of-argument) - [Raising a Failure exception to conceal the stacktrace](using/engine/special-failure-exception) diff --git a/docs/public/using/engine/index.md b/docs/public/using/engine/index.md index 7ef0244c..48b8fa83 100644 --- a/docs/public/using/engine/index.md +++ b/docs/public/using/engine/index.md @@ -11,6 +11,7 @@ How to: - [Match two strings and show diff on failure](match-two-strings) - [Extra story metadata - e.g. adding JIRA ticket numbers to stories](metadata) - [Story with parameters](parameterized-stories) +- [Story that rewrites given preconditions](rewrite-given) - [Story that rewrites itself](rewrite-story) - [Story that rewrites the sub key of an argument](rewrite-subkey-of-argument) - [Raising a Failure exception to conceal the stacktrace](special-failure-exception) diff --git a/docs/public/using/engine/rewrite-given.md b/docs/public/using/engine/rewrite-given.md new file mode 100644 index 00000000..b17e4281 --- /dev/null +++ b/docs/public/using/engine/rewrite-given.md @@ -0,0 +1,108 @@ +--- +title: Story that rewrites given preconditions +--- + + + +These examples show how to build stories that rewrite themselves +from program output (in-test snapshot testing) but that rewrite +the given preconditions. + +This is useful for changing + +``` +self.current_step.rewrite("argument").to("new output") +``` + + +# Code Example + + + +example.story: + +```yaml +Call API: + given: + mock api: + request: | + {"greeting": "hello"} + response: | + {"greeting": "hi"} + steps: + - Call API +``` +engine.py: + +```python +from hitchstory import BaseEngine, GivenDefinition, GivenProperty +from strictyaml import Map, Str + +class Engine(BaseEngine): + given_definition = GivenDefinition( + mock_api=GivenProperty( + schema=Map({"request": Str(), "response": Str()}), + inherit_via=GivenProperty.OVERRIDE, + ), + ) + + def __init__(self, rewrite=True): + self._rewrite = rewrite + + def call_api(self): + if self._rewrite: + self.given.rewrite("Mock API", "response").to("""{"greeting": "bye"}""") +``` + +With code: + +```python +from hitchstory import StoryCollection +from pathlib import Path +from engine import Engine + +``` + + + + + + +```python +StoryCollection(Path(".").glob("*.story"), Engine(rewrite=True)).ordered_by_name().play() + +``` + +Will output: +``` +RUNNING Call API in /path/to/working/example.story ... SUCCESS in 0.1 seconds. +``` + + + + +File example.story should now contain: + +``` +Call API: + given: + mock api: + request: | + {"greeting": "hello"} + response: | + {"greeting": "bye"} + steps: + - Call API +``` + + + + + + +!!! note "Executable specification" + + Documentation automatically generated from + rewrite-given.story + storytests. + diff --git a/docs/public/why-not/gherkin.md b/docs/public/why-not/gherkin.md index 2ac56e6f..960df2db 100644 --- a/docs/public/why-not/gherkin.md +++ b/docs/public/why-not/gherkin.md @@ -149,7 +149,7 @@ Type safety is a critical feature of programming languages. While type systems c At the other end of the spectrum is "stringly typed" code - the weakest of type systems, where everything is a string. Bash and Makefiles are both stringly typed and while it can be ok for short, simple scripts, it will make debugging painful when these scripts grow very large. -Gherkin is [stringly typed](https://www.techopedia.com/definition/31876/stringly-typed). Steps are parsed (often with regexes) and strings are pulled out and fed into step code. +Gherkin is [stringly typed](https://www.hanselman.com/blog/stringly-typed-vs-strongly-typed). Steps are parsed (often with regexes) and strings are pulled out and fed into step code. HitchStory, on the other hand, is based upon StrictYAML and bakes in schema based parsing.