11## Regression tests for typeshed
22
3- This directory contains regression tests for the stubs found elsewhere in the
4- typeshed repo.
3+ This directory contains code samples that act as a regression test for the
4+ standard library stubs found elsewhere in the typeshed repo.
55
6- ** This directory should * only* contain tests for functions and classes which
6+ ** This directory should * only* contain test cases for functions and classes which
77are known to have caused problems in the past, where the stubs are difficult to
88get right.** 100% test coverage for typeshed is neither necessary nor
99desirable, as it would lead to code duplication. Moreover, typeshed has
1010multiple other mechanisms for spotting errors in the stubs.
1111
1212### The purpose of these tests
1313
14- Different tests in this directory serve different purposes. For some stubs in
14+ Different test cases in this directory serve different purposes. For some stubs in
1515typeshed, the type annotations are complex enough that it's useful to have
1616basic sanity checks that test whether a type checker understands the intent of
1717the annotations correctly. Examples of tests like these are
18- ` stdlib/builtins/test_pow .py ` and ` stdlib/asyncio/test_gather .py ` .
18+ ` stdlib/builtins/check_pow .py ` and ` stdlib/asyncio/check_gather .py ` .
1919
20- Other tests , such as the tests for ` ExitStack ` in ` stdlib/test_contextlib .py `
21- and the tests for ` LogRecord ` in ` stdlib/test_logging .py ` , do not relate to
20+ Other test cases , such as the samples for ` ExitStack ` in ` stdlib/check_contextlib .py `
21+ and the samples for ` LogRecord ` in ` stdlib/check_logging .py ` , do not relate to
2222stubs where the annotations are particularly complex, but they * do* relate to
2323stubs where decisions have been taken that might be slightly unusual. These
24- tests serve a different purpose: to check that type checkers do not emit
24+ test cases serve a different purpose: to check that type checkers do not emit
2525false-positive errors for idiomatic usage of these classes.
2626
2727### How the tests work
2828
29+ The code in this directory is not intended to be directly executed. Instead,
30+ type checkers are run on the code, in order to check whether typing errors are
31+ emitted at the places where we want them to be.
32+
2933Some files in this directory simply contain samples of idiomatic Python, which
3034should not (if the stubs are correct) cause a type checker to emit any errors.
3135
@@ -52,19 +56,20 @@ provides a useful guide.
5256### Naming convention
5357
5458Use the same top-level name for the module / package you would like to test.
55- Use ` test_ ${thing}.py` naming pattern for individual test files.
59+ Use the ` check_ ${thing}.py` naming pattern for individual test files.
5660
57- By default, tests go into a test file with the same name as the stub file, prefixed with ` test_ ` .
58- For example: ` stdlib/test_contextlib .py ` .
61+ By default, test cases go into a file with the same name as the stub file, prefixed with ` check_ ` .
62+ For example: ` stdlib/check_contextlib .py ` .
5963
6064If that file becomes too big, we instead create a directory with files named after individual objects being tested.
61- For example: ` stdlib/builtins/test_dict .py ` .
65+ For example: ` stdlib/builtins/check_dict .py ` .
6266
6367### Differences to the rest of typeshed
6468
6569Unlike the rest of typeshed, this directory largely contains ` .py ` files. This
6670is because the purpose of this folder is to test the implications of typeshed
67- changes for end users.
71+ changes for end users, who will mainly be using ` .py ` files rather than ` .pyi `
72+ files.
6873
6974Another difference to the rest of typeshed is that the test cases in this
7075directory cannot always use modern syntax for type hints.
0 commit comments