Document how to use assert_type (#148)

Author: sobolevn

.github/workflows/test.yml

@@ -21,7 +21,7 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
         pytest-version: ["~=7.2", "~=8.1"]
         # TODO: remove after several new versions of mypy
-        mypy-version: ["~=1.7", "~=1.9"]
+        mypy-version: ["~=1.7", "~=1.10"]
 
     steps:
     - uses: actions/checkout@v4

README.md

@@ -33,6 +33,24 @@ just execute:
 pytest
 ```
 
+### Asserting types
+
+There are two ways to assert types.
+The custom one and regular [`typing.assert_type`](https://docs.python.org/3/library/typing.html#typing.assert_type).
+
+Our custom type assertion uses `reveal_type` helper and custom output matchers:
+
+```yml
+- case: using_reveal_type
+  main: |
+    instance = 1
+    reveal_type(instance)  # N: Revealed type is 'builtins.int'
+```
+
+This method also allows to use `# E:` for matching exact error messages and codes.
+
+But, you can also use regular `assert_type`, examples can be [found here](https://github.com/typeddjango/pytest-mypy-plugins/blob/master/pytest_mypy_plugins/tests/test-assert-type.yml).
+
 ### Paths
 
 The `PYTHONPATH` and `MYPYPATH` environment variables, if set, are passed to `mypy` on invocation.

pytest_mypy_plugins/tests/test-assert-type.yml

@@ -0,0 +1,19 @@
+- case: assert_type
+  main: |
+    from typing_extensions import assert_type
+
+    def x() -> int:
+        return 1
+
+    assert_type(x(), int)
+
+- case: assert_type_error
+  mypy_config: |
+    warn_unused_ignores = true
+  main: |
+    from typing_extensions import assert_type
+
+    def x() -> int:
+        return 1
+
+    assert_type(x(), str)  # type: ignore