|
1 | 1 | # Contributing to PyScript |
2 | 2 |
|
3 | | -Thank you for wanting to contribute to the PyScript project! |
4 | | - |
5 | | -## Table of contents |
6 | | - |
7 | | -- [Contributing to PyScript](#contributing-to-pyscript) |
8 | | - - [Table of contents](#table-of-contents) |
9 | | -- [Code of Conduct](#code-of-conduct) |
10 | | -- [Contributing](#contributing) |
11 | | - - [Reporting bugs](#reporting-bugs) |
12 | | - - [Creating useful issues](#creating-useful-issues) |
13 | | - - [Reporting security issues](#reporting-security-issues) |
14 | | - - [Asking questions](#asking-questions) |
15 | | - - [Setting up your local environment and developing](#setting-up-your-local-environment-and-developing) |
16 | | - - [Developing](#developing) |
17 | | - - [Rebasing changes](#rebasing-changes) |
18 | | - - [Building the docs](#building-the-docs) |
19 | | - - [Places to start](#places-to-start) |
20 | | - - [Setting up your local environment and developing](#setting-up-your-local-environment-and-developing) |
21 | | - - [Submitting a change](#submitting-a-change) |
22 | | -- [License terms for contributions](#license-terms-for-contributions) |
23 | | -- [Becoming a maintainer](#becoming-a-maintainer) |
24 | | -- [Trademarks](#trademarks) |
25 | | - |
26 | | -# Code of Conduct |
27 | | - |
28 | | -The [PyScript Code of Conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md) governs the project and everyone participating in it. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers or administrators as described in that document. |
29 | | - |
30 | | -# Contributing |
31 | | - |
32 | | -## Reporting bugs |
33 | | - |
34 | | -Bugs are tracked on the [project issues page](https://github.com/pyscript/pyscript/issues). Please check if your issue has already been filed by someone else by searching the existing issues before filing a new one. Once your issue is filed, it will be triaged by another contributor or maintainer. If there are questions raised about your issue, please respond promptly. |
35 | | - |
36 | | -## Creating useful issues |
37 | | - |
38 | | -- Use a clear and descriptive title. |
39 | | -- Describe the specific steps that reproduce the problem with as many details as possible so that someone can verify the issue. |
40 | | -- Describe the behavior you observed, and the behavior you had expected. |
41 | | -- Include screenshots if they help make the issue clear. |
42 | | - |
43 | | -## Reporting security issues |
44 | | - |
45 | | -If you aren't confident that it is appropriate to submit a security issue using the above process, you can e-mail it to security@pyscript.net |
46 | | - |
47 | | -## Asking questions |
48 | | - |
49 | | -If you have questions about the project, using PyScript, or anything else, please ask in the [PyScript forum](https://community.anaconda.cloud/c/tech-topics/pyscript). |
50 | | - |
51 | | -## Places to start |
52 | | - |
53 | | -If you would like to contribute to PyScript, but you aren't sure where to begin, here are some suggestions: |
54 | | - |
55 | | -- **Read over the existing documentation.** Are there things missing, or could they be clearer? Make some changes/additions to those documents. |
56 | | -- **Review the open issues.** Are they clear? Can you reproduce them? You can add comments, clarifications, or additions to those issues. If you think you have an idea of how to address the issue, submit a fix! |
57 | | -- **Look over the open pull requests.** Do you have comments or suggestions for the proposed changes? Add them. |
58 | | -- **Check out the examples.** Is there a use case that would be good to have sample code for? Create an example for it. |
59 | | - |
60 | | -## Setting up your local environment and developing |
61 | | - |
62 | | -If you would like to contribute to PyScript, you will need to set up a local development environment. The [following instructions](https://docs.pyscript.net/latest/contributing/#set-up-your-development-environment) will help you get started. |
63 | | - |
64 | | -You can also read about PyScript's [development process](https://docs.pyscript.net/latest/developers/) to learn how to contribute code to PyScript, how to run tests and what's the PR etiquette of the community! |
65 | | - |
66 | | -## License terms for contributions |
67 | | - |
68 | | -This Project welcomes contributions, suggestions, and feedback. All contributions, suggestions, and feedback you submitted are accepted under the [Apache 2.0](./LICENSE) license. You represent that if you do not own copyright in the code that you have the authority to submit it under the [Apache 2.0](./LICENSE) license. All feedback, suggestions, or contributions are not confidential. |
69 | | - |
70 | | -## Becoming a maintainer |
71 | | - |
72 | | -Contributors are invited to be maintainers of the project by demonstrating good decision making in their contributions, a commitment to the goals of the project, and consistent adherence to the [code of conduct](https://github.com/pyscript/governance/blob/main/CODE-OF-CONDUCT.md). New maintainers are invited by a 3/4 vote of the existing maintainers. |
73 | | - |
74 | | -## Trademarks |
75 | | - |
76 | | -The Project abides by the Organization's [trademark policy](https://github.com/pyscript/governance/blob/main/TRADEMARKS.md). |
77 | | - |
78 | | ---- |
79 | | - |
80 | | -Part of MVG-0.1-beta. |
81 | | -Made with love by GitHub. Licensed under the [CC-BY 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/). |
82 | | - |
83 | | -# Quick guide to pytest |
84 | | - |
85 | | -We make heavy usage of pytest. Here is a quick guide and collection of useful options: |
86 | | - |
87 | | -- To run all tests in the current directory and subdirectories: pytest |
88 | | - |
89 | | -- To run tests in a specific directory or file: pytest path/to/dir/test_foo.py |
90 | | - |
91 | | -- -s: disables output capturing |
92 | | - |
93 | | -- --pdb: in case of exception, enter a (Pdb) prompt so that you can inspect what went wrong. |
94 | | - |
95 | | -- -v: verbose mode |
96 | | - |
97 | | -- -x: stop the execution as soon as one test fails |
98 | | - |
99 | | -- -k foo: run only the tests whose full name contains foo |
100 | | - |
101 | | -- -k 'foo and bar' |
102 | | - |
103 | | -- -k 'foo and not bar' |
104 | | - |
105 | | -## Running integration tests under pytest |
106 | | - |
107 | | -make test is useful to run all the tests, but during the development is useful to have more control on how tests are run. The following guide assumes that you are in the directory pyscriptjs/tests/integration/. |
108 | | - |
109 | | -### To run all the integration tests, single or multi core |
110 | | - |
111 | | -$ pytest -xv |
112 | | -... |
113 | | - |
114 | | -test_00_support.py::TestSupport::test_basic[chromium] PASSED [ 0%] |
115 | | -test_00_support.py::TestSupport::test_console[chromium] PASSED [ 1%] |
116 | | -test_00_support.py::TestSupport::test_check_js_errors_simple[chromium] PASSED [ 2%] |
117 | | -test_00_support.py::TestSupport::test_check_js_errors_expected[chromium] PASSED [ 3%] |
118 | | -test_00_support.py::TestSupport::test_check_js_errors_expected_but_didnt_raise[chromium] PASSED [ 4%] |
119 | | -test_00_support.py::TestSupport::test_check_js_errors_multiple[chromium] PASSED [ 5%] |
120 | | -... |
121 | | - |
122 | | --x means "stop at the first failure". -v means "verbose", so that you can see all the test names one by one. We try to keep tests in a reasonable order, from most basic to most complex. This way, if you introduced some bug in very basic things, you will notice immediately. |
123 | | - |
124 | | -If you have the pytest-xdist plugin installed, you can run all the integration tests on 4 cores in parallel: |
125 | | - |
126 | | -$ pytest -n 4 |
127 | | - |
128 | | -### To run a single test, headless |
129 | | - |
130 | | -$ pytest test_01_basic.py -k test_pyscript_hello -s |
131 | | -... |
132 | | -[ 0.00 page.goto ] pyscript_hello.html |
133 | | -[ 0.01 request ] 200 - fake_server - http://fake_server/pyscript_hello.html |
134 | | -... |
135 | | -[ 0.17 console.info ] [py-loader] Downloading pyodide-x.y.z... |
136 | | -[ 0.18 request ] 200 - CACHED - https://cdn.jsdelivr.net/pyodide/vx.y.z/full/pyodide.js |
137 | | -... |
138 | | -[ 3.59 console.info ] [pyscript/main] PyScript page fully initialized |
139 | | -[ 3.60 console.log ] hello pyscript |
140 | | - |
141 | | --k selects tests by pattern matching as described above. -s instructs pytest to show the output to the terminal instead of capturing it. In the output you can see various useful things, including network requests and JS console messages. |
142 | | - |
143 | | -### To run a single test, headed |
144 | | - |
145 | | -$ pytest test_01_basic.py -k test_pyscript_hello -s --headed |
146 | | -... |
147 | | - |
148 | | -Same as above, but with --headed the browser is shown in a window, and you can interact with it. The browser uses a fake server, which means that HTTP requests are cached. |
149 | | - |
150 | | -Unfortunately, in this mode source maps does not seem to work, and you cannot debug the original typescript source code. This seems to be a bug in playwright, for which we have a workaround: |
151 | | - |
152 | | -$ pytest test_01_basic.py -k test_pyscript_hello -s --headed --no-fake-server |
153 | | -... |
154 | | - |
155 | | -As the name implies, -no-fake-server disables the fake server: HTTP requests are not cached, but source-level debugging works. |
156 | | - |
157 | | -Finally: |
158 | | - |
159 | | -$ pytest test_01_basic.py -k test_pyscript_hello -s --dev |
160 | | -... |
161 | | - |
162 | | ---dev implies --headed --no-fake-server. In addition, it also automatically open chrome dev tools. |
163 | | - |
164 | | -### To run only main thread or worker tests |
165 | | - |
166 | | -By default, we run each test twice: one with execution_thread = "main" and one with execution_thread = "worker". If you want to run only half of them, you can use -m: |
167 | | - |
168 | | -$ pytest -m main # run only the tests in the main thread |
169 | | -$ pytest -m worker # ron only the tests in the web worker |
170 | | - |
171 | | -## Fake server, HTTP cache |
172 | | - |
173 | | -By default, our test machinery uses a playwright router which intercepts and cache HTTP requests, so that for example you don't have to download pyodide again and again. This also enables the possibility of running tests in parallel on multiple cores. |
174 | | - |
175 | | -The cache is stored using the pytest-cache plugin, which means that it survives across sessions. |
176 | | - |
177 | | -If you want to temporarily disable the cache, the easiest thing is to use --no-fake-server, which bypasses it completely. |
178 | | - |
179 | | -If you want to clear the cache, you can use the special option --clear-http-cache: |
180 | | - |
181 | | -NOTE: this works only if you are inside tests/integration, or if you explicitly specify tests/integration from the command line. This is due to how pytest decides to search for and load the various conftest.py. |
| 3 | +Please see our guide to contributing to PyScript |
| 4 | +[in our documentation](https://docs.pyscript.net/latest/contributing/). |
0 commit comments