Skip to content

Commit 3113b05

Browse files
cztomczakcztomczak
committed
Update Contributing-code.md - add more info on unit tests
1 parent aadb9e8 commit 3113b05

1 file changed

Lines changed: 108 additions & 49 deletions

File tree

‎docs/Contributing-code.md‎

Lines changed: 108 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -5,70 +5,129 @@ contribute new code to the CEF Python project.
55

66

77
Table of contents:
8-
* [Requirements](#requirements)
9-
* [Tools](#tools)
10-
* [Python / Cython style guidelines](#python--cython-style-guidelines)
11-
* [How to debug CEF stack trace](#how-to-debug-cef-stack-trace)
8+
* [Pull requests](#pull-requests)
9+
* [Code style](#code-style)
10+
* [Code warnings in PyCharm](#code-warnings-in-pycharm)
11+
* [Test your code](#test-your-code)
12+
* [API docs](#api-docs)
13+
* [Unit tests](#unit-tests)
14+
* [Platforms](#platforms)
15+
* [Authors](#authors)
16+
* [Updating CEF version](#updating-cef-version)
1217

1318

14-
## Requirements
19+
## Pull requests
1520

1621
- Pull requests should be sent for the master branch
17-
- Your code should follow the [style guidelines](#python--cython-style-guidelines)
1822
- Pull request should implement only one feature at a time, so that
1923
reviewing them is easy. If you have implemented several features
2024
then send them as sepearate pull requests. If not sure then ask
2125
on the [Forum](https://groups.google.com/group/cefpython).
22-
- When adding or exposing new API you should update API docs as well
23-
(the api/ directory)
24-
- Update or create new documents if necessary
25-
- To update table of contents (TOC) in the document run the
26-
tools/toc.py script
27-
- To update API index run the tools/apidocs.py tool
28-
- When adding or exposing new API you should create unit tests
29-
for the new functionality (the unittests/ directory). If creating
30-
unit tests is not feasible or extremely difficult then you should
31-
at least provide an example through [gist.github.com](https://gist.github.com/).
32-
- Test your code before sending PR. Run unit tests. Run various
33-
examples to see if your new code didn't break them. Running unit tests,
34-
hello_world.py, tutorial.py and screenshot.py examples is an absolute
35-
minimum that you must do. Please try also testing examples for
36-
various GUI frameworks.
37-
- Python code should be tested using multiple Python versions. See
38-
[Issue #249](../../../issue/249) ("How to use pyenv to manage multiple
39-
Python versions on Ubuntu/Mac")
40-
- In most cases new code should run fine on all platforms, but in
41-
some cases it might be required to test on all platforms before
42-
PR is merged
43-
- In your pull request modify also the [Authors](../Authors) file
44-
to add your name and encoded email
45-
- If you want to update CEF version then take a look at
46-
[Issue #264](../../../issues/264)("Workflow when updating CEF version").
47-
- Edit Python/Cython code using PyCharm IDE to see if there are any
48-
style warnings for the file you're editing. If you don't see a green
49-
tick in the upper-right corner of the editor's code area that means
50-
something is wrong with your code and must be fixed. See the Tools
51-
section below for how to configure PyCharm for editing cefpython's
52-
code.
53-
54-
55-
## Tools
56-
57-
It is recommended to use PyCharm IDE to edit Cython code. See
58-
[Issue #232](../../../issues/232)("Using PyCharm IDE to edit
59-
cefpython's Cython code") for details.
6026

6127

62-
## Python / Cython style guidelines
28+
## Code style
6329

6430
* Try to comply with the [PEP 8 style guide](http://www.python.org/dev/peps/pep-0008/)
65-
* Limit all lines to a maximum of 79 characters (comments should be shorter, max 60-65 chars)
31+
* Limit all lines to a maximum of 79 characters (comments should
32+
be shorter, max 60-65 chars)
6633
* Do your best for the new code to be consistent with existing code base
6734
* Use 4 spaces for indentation
6835
* Commit unix-style newlines (\n)
6936

7037

71-
## How to debug CEF stack trace
38+
## Code warnings in PyCharm
39+
40+
Edit Python/Cython code using PyCharm IDE to see if there are any
41+
style warnings for the file you're editing. If you don't see a green
42+
tick in the upper-right corner of the editor's code area that means
43+
something is wrong with your code and must be fixed. See
44+
[Issue #232](../../../issues/232)("Using PyCharm IDE to edit
45+
cefpython's Cython code") for details.
46+
47+
48+
## Test your code
49+
50+
Test your code before sending PR. Run unit tests. Run various
51+
examples to see if your new code didn't break them. Running unit tests,
52+
hello_world.py, tutorial.py and screenshot.py examples is an absolute
53+
minimum that you must do. Please try also testing examples for
54+
various GUI frameworks.
55+
56+
Pure Python code should be tested using multiple Python versions. See
57+
[Issue #249](../../../issue/249) ("How to use pyenv to manage multiple
58+
Python versions on Ubuntu/Mac").
59+
60+
61+
## API docs
62+
63+
When adding or exposing new API you should update API docs as well
64+
(the api/ directory):
65+
66+
- Update or create new documents if necessary
67+
- To update table of contents (TOC) in the document run the
68+
tools/toc.py script
69+
- To update API index run the tools/apidocs.py script
70+
71+
72+
## Unit tests
73+
74+
When adding or exposing new API you should create unit tests
75+
for the new functionality (the unittests/ directory).If creating
76+
unit tests is not feasible or extremely difficult then you should
77+
at least provide an example through [gist.github.com](https://gist.github.com/).
78+
79+
CEF imposes some limits on the structure of unit tests. Most of
80+
CEF API requires that CEF is initialized before its API is used.
81+
So each test must start with a call to cef.Initialize, however
82+
CEF can be initialized only once during app's lifetime. The way
83+
python unittest module works doesn't allow to define for example
84+
test methods named "test_1_initialize", "test_2_some", "test_3_shutdown",
85+
after doing so some strange things happen (maybe unittest is
86+
running these methods in separate threads). So with these
87+
restrictions the way it works currently is that there is ongle
88+
single method named "test_main" in which muliple sub-tests are
89+
run. A function named "subtest_message" was defined to be able
90+
to output results of the multiple subtests that are running inside
91+
the "test_main" method.
92+
93+
In main_test.py there were implemented automated checks in handlers
94+
and in the external object. When class (handler or external)
95+
defines a property that ends with "_True" or "_False" then it will
96+
be automatically checked whether it asserts to these values just
97+
before CEF shutdown. There is one limitation for these type
98+
of automatic asserts - its values should be set first
99+
before executing normal kind of asserts, so that they are reported
100+
correctly, otherwise you might see misleading reports about failed
101+
asserts.
102+
103+
CEF Python's unit tests are run using a special script named
104+
_test_runner.py. This script implements a way to run all unit
105+
tests (by default with no arguments passed) and also implements
106+
some special features like Isolated Tests along with some other
107+
minor features for CEF special case. An isolated test is run
108+
using a separate Python intepreter (a separate process). To mark
109+
a Test class an isolated test just append "_IsolatedTest" in
110+
its name. Isolated tests are required for running CEF tests
111+
properly. The _test_runner.py script allows to run multiple CEF
112+
isolated tests in one execution. You can define multiple
113+
test classes like "MyTest1_IsolatedTest" and "MyTest2_IsolatedTest"
114+
in one file, but keep in mind that you can define only a single
115+
test method in these classes as explained earlier. Each of such
116+
tests should have logic to initialize and shutdown CEF properly.
117+
118+
119+
## Platforms
120+
121+
In most cases new code should run fine on all platforms, but in
122+
some cases it might be required to test on all platforms before
123+
PR is merged.
124+
125+
## Authors
126+
127+
In your pull request modify also the [Authors](../Authors) file
128+
to add your name and encoded email.
129+
130+
## Updating CEF version
72131

73-
On Linux/Mac you can use gdb/lldb, see instructions on the
74-
[KB page](Knowledge-Base.md#python-crashes-with-segmentation-fault---how-to-debug).
132+
If you want to update CEF version then take a look at
133+
[Issue #264](../../../issues/264)("Workflow when updating CEF version").

0 commit comments

Comments
 (0)