diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 25bd9b37..b7149084 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -3,6 +3,7 @@ on:
push:
tags:
- v[0-9]+.[0-9]+.[0-9]+
+ - deployed_docs
jobs:
build:
@@ -26,3 +27,8 @@ jobs:
#EXTRA_PACKAGES: build-base
# GITHUB_DOMAIN: github.myenterprise.com
REQUIREMENTS: doc_requirements.txt
+ - name: tag docs
+ uses: tvdias/github-tagger@v0.0.1
+ with:
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+ tag: deployed_docs
diff --git a/README.md b/README.md
index e3bb1b23..477e4ab2 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,9 @@
-# inline-snapshot
-
+
-
-create and update inline snapshots in your code.
-
+
+ 
+
@@ -15,6 +14,8 @@ create and update inline snapshots in your code.
[](https://15r10nk.github.io/inline-snapshot/contributing/#coverage)
[](https://github.com/sponsors/15r10nk)
+
+
## Installation
You can install "inline-snapshot" via [pip](https://pypi.org/project/pip/):
diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg
new file mode 100644
index 00000000..30faccc5
--- /dev/null
+++ b/docs/assets/logo.svg
@@ -0,0 +1,164 @@
+
+
diff --git a/docs/cmp_snapshot.md b/docs/cmp_snapshot.md
index 1440c564..a53f452f 100644
--- a/docs/cmp_snapshot.md
+++ b/docs/cmp_snapshot.md
@@ -2,40 +2,119 @@
A snapshot can be compared against any value with `<=` or `>=`.
This can be used to create a upper/lower bound for some result.
+The snapshot value can be trimmed to the lowest/largest valid value.
Example:
-
-```python
-def some_algo():
- ...
- result = 42
- iterations = 2
- ...
- return result, iterations
+=== "original code"
+
+ ```python
+ def gcd(x, y):
+ iterations = 0
+ if x > y:
+ small = y
+ else:
+ small = x
+ for i in range(1, small + 1):
+ iterations += 1
+ if (x % i == 0) and (y % i == 0):
+ gcd = i
+ return gcd, iterations
-def test_something():
- result, iterations = some_algo()
- assert result == snapshot(42)
- assert iterations <= snapshot(2)
-```
+ def test_gcd():
+ result, iterations = gcd(12, 18)
+
+ assert result == snapshot()
+ assert iterations <= snapshot()
+ ```
+
+=== "--inline-snapshot=create"
+
+ ```python
+ def gcd(x, y):
+ iterations = 0
+ if x > y:
+ small = y
+ else:
+ small = x
+ for i in range(1, small + 1):
+ iterations += 1
+ if (x % i == 0) and (y % i == 0):
+ gcd = i
+
+ return gcd, iterations
+
+
+ def test_gcd():
+ result, iterations = gcd(12, 18)
+
+ assert result == snapshot(6)
+ assert iterations <= snapshot(12)
+ ```
+
+=== "optimized code "
+
+ ```python
+ def gcd(x, y):
+ # use Euclidean Algorithm
+ iterations = 0
+ while y:
+ iterations += 1
+ x, y = y, x % y
+ return abs(x), iterations
+
+
+ def test_gcd():
+ result, iterations = gcd(12, 18)
+
+ assert result == snapshot(6)
+ assert iterations <= snapshot(12)
+ ```
+
+=== "--inline-snapshot=trim"
+
+ ```python
+ def gcd(x, y):
+ # use Euclidean Algorithm
+ iterations = 0
+ while y:
+ iterations += 1
+ x, y = y, x % y
+ return abs(x), iterations
+
+
+ def test_gcd():
+ result, iterations = gcd(12, 18)
+
+ assert result == snapshot(6)
+ assert iterations <= snapshot(3)
+ ```
!!! warning
This should not be used to check for any flaky values like the runtime of some code, because it will randomly break your tests.
The same snapshot value can also be used in multiple assertions.
-The snapshot value in the following case would be `6`.
-
-```python
-def test_something():
- value = snapshot()
+=== "original code"
+
+ ```python
+ def test_something():
+ value = snapshot()
+
+ assert 5 <= value
+ assert 6 <= value
+ ```
+=== "--inline-snapshot=create"
+
+ ```python
+ def test_something():
+ value = snapshot(6)
- assert 5 <= value
- assert 6 <= value
-```
+ assert 5 <= value
+ assert 6 <= value
+ ```
## pytest options
diff --git a/docs/eq_snapshot.md b/docs/eq_snapshot.md
index 534b6fd7..d5dd6472 100644
--- a/docs/eq_snapshot.md
+++ b/docs/eq_snapshot.md
@@ -5,11 +5,19 @@ The value gets recorded if the snapshot is undefined (`snapshot()`)
Example:
-
-```python
-def test_something():
- assert 2 + 2 == snapshot(4)
-```
+=== "original code"
+
+ ```python
+ def test_something():
+ assert 2 + 2 == snapshot()
+ ```
+
+=== "--inline-snapshot=create"
+
+ ```python
+ def test_something():
+ assert 2 + 2 == snapshot(4)
+ ```
## pytest options
diff --git a/docs/getitem_snapshot.md b/docs/getitem_snapshot.md
index 844a1002..2a045cd3 100644
--- a/docs/getitem_snapshot.md
+++ b/docs/getitem_snapshot.md
@@ -5,23 +5,25 @@ This sub-snapshots can be used like a normal snapshot.
Example:
-```python
-def test_something():
- s = snapshot()
-
- assert s["a"] == 4
- assert s["b"] == 5
-```
-
-generates:
-
-```python
-def test_something():
- s = snapshot({"a": 4, "b": 5})
-
- assert s["a"] == 4
- assert s["b"] == 5
-```
+=== "original code"
+
+ ```python
+ def test_something():
+ s = snapshot()
+
+ assert s["a"] == 4
+ assert s["b"] == 5
+ ```
+
+=== "--inline-snapshot=create"
+
+ ```python
+ def test_something():
+ s = snapshot({"a": 4, "b": 5})
+
+ assert s["a"] == 4
+ assert s["b"] == 5
+ ```
`s[key]` can be used with every normal snapshot operation including `s[key1][key2]`.
diff --git a/docs/in_snapshot.md b/docs/in_snapshot.md
index e7290c7d..13b24d8c 100644
--- a/docs/in_snapshot.md
+++ b/docs/in_snapshot.md
@@ -4,31 +4,33 @@ It is possible to check if an value is in a snapshot. The value of the generated
Example:
-
-```python
-def test_something():
- s = snapshot()
-
- assert 5 in s
- assert 5 in s
- assert 8 in s
-
- for v in ["a", "b"]:
- assert v in s
-```
-
-
-```python
-def test_something():
- s = snapshot([5, 8, "a", "b"])
-
- assert 5 in s
- assert 5 in s
- assert 8 in s
-
- for v in ["a", "b"]:
- assert v in s
-```
+=== "original code"
+
+ ```python
+ def test_something():
+ s = snapshot()
+
+ assert 5 in s
+ assert 5 in s
+ assert 8 in s
+
+ for v in ["a", "b"]:
+ assert v in s
+ ```
+
+=== "--inline-snapshot=create"
+
+ ```python
+ def test_something():
+ s = snapshot([5, 8, "a", "b"])
+
+ assert 5 in s
+ assert 5 in s
+ assert 8 in s
+
+ for v in ["a", "b"]:
+ assert v in s
+ ```
## pytest options
diff --git a/docs/index.md b/docs/index.md
index 4ff0e5c1..d8f0562c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,7 @@
+
+--8<-- "README.md:Header"
+
+
# Welcome to inline-snapshot
inline-snapshot can be used for different things:
@@ -13,68 +17,65 @@ The value is converted with `repr()` and stored in the source file as argument o
## Usage
-You can use `snapshot()` instead of the value which you want to compare with.
+You can use `snapshot()` instead of the value which you want to compare with and run the tests to record the correct values.
-
-```python
-from inline_snapshot import snapshot
+=== "original code"
+
+ ```python
+ from inline_snapshot import snapshot
-def something():
- return 1548 * 18489
+ def something():
+ return 1548 * 18489
-def test_something():
- assert something() == snapshot()
-```
-You can now run the tests and record the correct values.
+ def test_something():
+ assert something() == snapshot()
+ ```
-```bash
-pytest --inline-snapshot=create
-```
-
-```python
-from inline_snapshot import snapshot
+=== "--inline-snapshot=create"
+
+ ```python
+ from inline_snapshot import snapshot
-def something():
- return 1548 * 18489
+ def something():
+ return 1548 * 18489
-def test_something():
- assert something() == snapshot(28620972)
-```
-Your tests will break, if you change your code by adding `// 18`.
+ def test_something():
+ assert something() == snapshot(28620972)
+ ```
-
-```python
-def something():
- return (1548 * 18489) // 18
+Your tests will break, if you change your code by adding `// 18`.
+Maybe that is correct and you should fix your code, or
+your code is correct and you want to update your test results.
+=== "changed code"
+
+ ```python
+ def something():
+ return (1548 * 18489) // 18
-def test_something():
- assert something() == snapshot(28620972)
-```
-Maybe that is correct and you should fix your code, or
-your code is correct and you want to update your test results.
+ def test_something():
+ assert something() == snapshot(28620972)
+ ```
-``` bash
-pytest --inline-snapshot=fix
-```
-
-```python
-def something():
- return (1548 * 18489) // 18
+=== "--inline-snapshot=fix"
+
+ ```python
+ def something():
+ return (1548 * 18489) // 18
-def test_something():
- assert something() == snapshot(1590054)
-```
+ def test_something():
+ assert something() == snapshot(1590054)
+ ```
Please verify the new results. `git diff` will give you a good overview over all changed results.
Use `pytest -k test_something --inline-snapshot=fix` if you only want to change one test.
@@ -102,72 +103,94 @@ You can use `snapshot(x)` like you can use `x` in your assertion with a limited
It is possible to place `snapshot()` anywhere in the tests and reuse it multiple times.
-
-```python
-def something():
- ...
+
+=== "original code"
+
+
+ ```python
+ def something():
+ return 21 * 2
+
+
+ result = snapshot()
+
+
+ def test_something():
+ ...
+ assert something() == result
+
+
+ def test_something_again():
+ ...
+ assert something() == result
+ ```
+
+=== "--inline-snapshot=create"
+
+
+ ```python
+ def something():
+ return 21 * 2
-result = snapshot()
+ result = snapshot(42)
-def test_something():
- ...
- assert something() == result
+ def test_something():
+ ...
+ assert something() == result
-def test_something_again():
- ...
- assert something() == result
-```
+ def test_something_again():
+ ...
+ assert something() == result
+ ```
`snapshot()` can also be used in loops:
-
-```python
-def test_loop():
- for name in ["Mia", "Eva", "Leo"]:
- assert len(name) == snapshot(3)
-```
+=== "original code"
+
+ ```python
+ def test_loop():
+ for name in ["Mia", "Eva", "Leo"]:
+ assert len(name) == snapshot()
+ ```
+=== "--inline-snapshot=create"
+
+ ```python
+ def test_loop():
+ for name in ["Mia", "Eva", "Leo"]:
+ assert len(name) == snapshot(3)
+ ```
or passed as an argument to a function:
-
-```python
-def check_string_functions(string, snapshot_value):
- assert len(string) == snapshot_value["length"]
- assert string.upper() == snapshot_value["upper_result"]
- assert string.lower() == snapshot_value["lower_result"]
+=== "original code"
+
+ ```python
+ def check_string_len(string, snapshot_value):
+ assert len(string) == snapshot_value
-def test_string_functions():
- check_string_functions("abc", snapshot())
- check_string_functions("User", snapshot())
- check_string_functions("UPPER", snapshot())
-```
-Which will create the following values:
+ def test_string_len():
+ check_string_len("abc", snapshot())
+ check_string_len("1234", snapshot())
+ check_string_len(".......", snapshot())
+ ```
-
-``` python
-def check_string_functions(string, snapshot_value):
- assert len(string) == snapshot_value["length"]
- assert string.upper() == snapshot_value["upper_result"]
- assert string.lower() == snapshot_value["lower_result"]
+=== "--inline-snapshot=create"
+
+ ``` python
+ def check_string_len(string, snapshot_value):
+ assert len(string) == snapshot_value
-def test_string_functions():
- check_string_functions(
- "abc", snapshot({"length": 3, "upper_result": "ABC", "lower_result": "abc"})
- )
- check_string_functions(
- "User", snapshot({"length": 4, "upper_result": "USER", "lower_result": "user"})
- )
- check_string_functions(
- "UPPER",
- snapshot({"length": 5, "upper_result": "UPPER", "lower_result": "upper"}),
- )
-```
+ def test_string_len():
+ check_string_len("abc", snapshot(3))
+ check_string_len("1234", snapshot(4))
+ check_string_len(".......", snapshot(7))
+ ```
@@ -176,37 +199,60 @@ def test_string_functions():
You can use almost any python datatype and also complex values like `datatime.date`, because `repr()` is used to convert the values to a source code.
It might be necessary to import the right modules to match the `repr()` output.
-
-```python
-from inline_snapshot import snapshot
-import datetime
+=== "original code"
+
+ ```python
+ from inline_snapshot import snapshot
+ import datetime
-def something():
- return {
- "name": "hello",
- "one number": 5,
- "numbers": list(range(10)),
- "sets": {1, 2, 15},
- "datetime": datetime.date(1, 2, 22),
- "complex stuff": 5j + 3,
- "bytes": b"fglecg\n\x16",
- }
+ def something():
+ return {
+ "name": "hello",
+ "one number": 5,
+ "numbers": list(range(10)),
+ "sets": {1, 2, 15},
+ "datetime": datetime.date(1, 2, 22),
+ "complex stuff": 5j + 3,
+ "bytes": b"fglecg\n\x16",
+ }
+
+
+ def test_something():
+ assert something() == snapshot()
+ ```
+=== "--inline-snapshot=create"
+
+ ```python
+ from inline_snapshot import snapshot
+ import datetime
-def test_something():
- assert something() == snapshot(
- {
+ def something():
+ return {
"name": "hello",
"one number": 5,
- "numbers": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+ "numbers": list(range(10)),
"sets": {1, 2, 15},
"datetime": datetime.date(1, 2, 22),
- "complex stuff": (3 + 5j),
+ "complex stuff": 5j + 3,
"bytes": b"fglecg\n\x16",
}
- )
-```
+
+
+ def test_something():
+ assert something() == snapshot(
+ {
+ "name": "hello",
+ "one number": 5,
+ "numbers": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+ "sets": {1, 2, 15},
+ "datetime": datetime.date(1, 2, 22),
+ "complex stuff": (3 + 5j),
+ "bytes": b"fglecg\n\x16",
+ }
+ )
+ ```
The code is generated in the following way:
@@ -215,18 +261,29 @@ The code is generated in the following way:
3. Strings which contain newlines are converted to triple quoted strings.
!!! note
- Missing newlines at start or end are escaped.
-
-
- ``` python
- def test_something():
- assert "first line\nsecond line" == snapshot(
- """\
- first line
- second line\
- """
- )
- ```
+ Missing newlines at start or end are escaped (since 0.4.0).
+
+ === "original code"
+
+ ``` python
+ def test_something():
+ assert "first line\nsecond line" == snapshot(
+ """first line
+ second line"""
+ )
+ ```
+
+ === "--inline-snapshot=update"
+
+ ``` python
+ def test_something():
+ assert "first line\nsecond line" == snapshot(
+ """\
+ first line
+ second line\
+ """
+ )
+ ```
4. The code is formatted with black.
diff --git a/docs/pytest.md b/docs/pytest.md
index 859ec45c..73882696 100644
--- a/docs/pytest.md
+++ b/docs/pytest.md
@@ -8,7 +8,9 @@ inline-snapshot comes with a pytest plugin which offers the following options.
- **--inline-snapshot=update**:
update snapshots if they changed their representation (result of `repr()`)
- **--inline-snapshot=trim**:
- changes the snapshot in a way which will make the snapshot more precise.
+ changes the snapshot in a way which will make the snapshot more precise (see [`value in snapshot()`](in_snapshot.md) and [`snapshot()[key]`](getitem_snapshot.md) ).
+
+
- **--inline-snapshot=fix**:
change snapshots which are currently breaking your tests (where the result of the snapshot operation is `False`).
@@ -19,4 +21,5 @@ pytest --inline-snapshot=trim,fix
```
### --inline-snapshot-disable
- disable all the snapshot logic. `snapshot(x)` will just return `x`.
+
+disables all the snapshot logic. `snapshot(x)` will just return `x`.
diff --git a/mkdocs.yml b/mkdocs.yml
index 92ac4233..38dd0e73 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,6 +7,8 @@ theme:
name: material
features:
- toc.follow
+ palette:
+ primary: teal
watch:
- CONTRIBUTING.md
@@ -39,6 +41,8 @@ markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
+- pymdownx.tabbed:
+ alternate_style: true
plugins:
- mkdocstrings:
@@ -47,6 +51,8 @@ plugins:
options:
show_root_heading: true
show_source: false
+- social
+- search
extra:
social:
diff --git a/noxfile.py b/noxfile.py
index cf04ce27..d50e0b19 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -51,5 +51,11 @@ def test(session):
@session(python="python3.10")
def docs(session):
- session.install("mkdocs", "mkdocs-material", "mkdocstrings")
+ session.install("mkdocs", "mkdocs-material[imaging]", "mkdocstrings")
session.run("mkdocs", "build", *session.posargs)
+
+
+@session(python="python3.10")
+def docs_serve(session):
+ session.install("mkdocs", "mkdocs-material[imaging]", "mkdocstrings")
+ session.run("mkdocs", "serve", *session.posargs)
diff --git a/poetry.lock b/poetry.lock
index ba2de8f2..ac8a0717 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1163,4 +1163,4 @@ testing = ["big-O", "flake8 (<5)", "jaraco.functools", "jaraco.itertools", "more
[metadata]
lock-version = "2.0"
python-versions = "^3.7"
-content-hash = "94cc76ab085d76ff8cba32bbb38f9029a7e008d0882e3212ae6567fbaa97d6dc"
+content-hash = "4a753af4b7238ff8ce1aee3083f03166451da4fbb26c69959ab1177f7f6a12d8"
diff --git a/pyproject.toml b/pyproject.toml
index 0df9e822..2ce9c4de 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -68,7 +68,7 @@ pytest-subtests = "^0.11.0"
[tool.poetry.group.doc.dependencies]
mkdocs = "^1.4.2"
-mkdocs-material = "^8.5.10"
+mkdocs-material = {extras = ["imaging"], version = "^8.5.10"}
mkdocstrings = {extras = ["python-legacy"], version = "^0.19.0"}
[tool.poetry.plugins.pytest11]