##// END OF EJS Templates
docs: updates to contributor documentation #4039
lisaq -
r271:401985cc default
parent child
Show More
@@ -1,47 +1,47
1 1 README - Quickstart
2 2 ===================
3 3
4 This folder contains functional tests and the automation of specification
4 This folder contains the functional tests and automation of specification
5 5 examples. Details about testing can be found in
6 6 `/docs-internal/testing/index.rst`.
7 7
8 8
9 9 Setting up your Rhodecode Enterprise instance
10 10 ---------------------------------------------
11 11
12 12 The tests will create users and repositories as needed, so you can start with a
13 13 new and empty instance.
14 14
15 15 Use the following example call for the database setup of Enterprise::
16 16
17 17 paster setup-rhodecode \
18 18 --user=admin \
19 19 --email=admin@example.com \
20 20 --password=secret \
21 21 --api-key=9999999999999999999999999999999999999999 \
22 22 your-enterprise-config.ini
23 23
24 This way the username, password and auth token of the admin user will match the
24 This way the username, password, and auth token of the admin user will match the
25 25 defaults from the test run.
26 26
27 27
28 28 Usage
29 29 -----
30 30
31 31 1. Make sure your Rhodecode Enterprise instance is running at
32 32 http://localhost:5000.
33 33
34 34 2. Enter `nix-shell` from the acceptance_tests folder::
35 35
36 36 cd acceptance_tests
37 nix-shell -I ~/dev
37 nix-shell
38 38
39 39 Make sure that `rcpkgs` and `rcnixpkgs` are available on the nix path.
40 40
41 41 3. Run the tests::
42 42
43 43 py.test -c example.ini -vs
44 44
45 45 The parameter ``-vs`` allows you to see debugging output during the test
46 46 run. Check ``py.test --help`` and the documentation at http://pytest.org to
47 47 learn all details about the test runner.
@@ -1,19 +1,19
1 1 .. _contributing:
2 2
3 3 Contributing to RhodeCode
4 4 =========================
5 5
6 6
7 7
8 Welcome to contribution guides and development docs of RhodeCode.
8 Welcome to the contribution guides and development docs of RhodeCode.
9 9
10 10
11 11
12 12 .. toctree::
13 13 :maxdepth: 1
14 14
15 15 testing/index
16 16 dev-setup
17 17 db-schema
18 18 dev-settings
19 19 api
@@ -1,52 +1,52
1 1 =======================
2 2 DB Schema and Migration
3 3 =======================
4 4
5 To create or alter tables in the database it's necessary to change a couple of
5 To create or alter tables in the database, it's necessary to change a couple of
6 6 files, apart from configuring the settings pointing to the latest database
7 7 schema.
8 8
9 9
10 10 Database Model and ORM
11 11 ----------------------
12 12
13 13 On ``rhodecode.model.db`` you will find the database definition of all tables and
14 fields. Any fresh install database will be correctly created by the definitions
15 here. So, any change to this files will affect the tests without having to change
14 fields. Any freshly installed database will be correctly created by the definitions
15 here. So, any change to this file will affect the tests without having to change
16 16 any other file.
17 17
18 A second layer are the businness classes that are inside ``rhodecode.model``.
18 A second layer are the business classes inside ``rhodecode.model``.
19 19
20 20
21 21 Database Migration
22 22 ------------------
23 23
24 24 Three files play a role when creating database migrations:
25 25
26 26 * Database schema inside ``rhodecode.lib.dbmigrate``
27 27 * Database version inside ``rhodecode.lib.dbmigrate``
28 28 * Configuration ``__dbversion__`` at ``rhodecode.__init__``
29 29
30 30
31 31 Schema is a snapshot of the database version BEFORE the migration. So, it's
32 32 the initial state before any changes were added. The name convention is
33 the latest release version where the snapshot were created, and not the
33 the latest release version where the snapshot was created, and not the
34 34 target version of this code.
35 35
36 36 Version is the method that will define how to UPGRADE/DOWNGRADE the database.
37 37
38 38 ``rhodecode.__init__`` contains only a variable that defines up to which version of
39 39 the database will be used to upgrade. Eg.: ``__dbversion__ = 45``
40 40
41 41
42 42 For examples on how to create those files, please see the existing code.
43 43
44 44
45 45 Migration Command
46 46 ^^^^^^^^^^^^^^^^^
47 47
48 After you changed the database ORM and migration files, you can run::
48 After you've changed the database ORM and migration files, you can run::
49 49
50 50 paster upgrade-db <ini-file>
51 51
52 And the database will be upgraded up to the version defined in the ``__init__`` file. No newline at end of file
52 The database will be upgraded up to the version defined in the ``__init__`` file. No newline at end of file
@@ -1,46 +1,46
1 1
2 2 ==========================
3 3 Settings for Development
4 4 ==========================
5 5
6 6
7 7 We have a few settings which are intended to be used only for development
8 8 purposes. This section contains an overview of them.
9 9
10 10
11 11
12 12 `debug_style`
13 13 =============
14 14
15 15 Enables the section "Style" in the application. This section provides an
16 overview of all components which are found in the frontend style of the
16 overview of all components which are found in the frontend of the
17 17 application.
18 18
19 19
20 20
21 21 `vcs.start_server`
22 22 ==================
23 23
24 24 Starts the server as a subprocess while the system comes up. Intended usage is
25 25 to ease development.
26 26
27 27
28 28
29 29 `[logging]`
30 30 ===========
31 31
32 Use this to configure loggig to your current needs. The documentation of
33 Python's `logging` module explains all details. The following snippets are
34 useful for day to day development work.
32 Use this to configure logging to your current needs. The documentation of
33 Python's `logging` module explains all of the details. The following snippets
34 are useful for day to day development work.
35 35
36 36
37 37 Mute SQL output
38 38 ---------------
39 39
40 40 They come out of the package `sqlalchemy.engine`::
41 41
42 42 [logger_sqlalchemy]
43 43 level = WARNING
44 44 handlers = console_sql
45 45 qualname = sqlalchemy.engine
46 46 propagate = 0
@@ -1,141 +1,141
1 1
2 2 ===================
3 3 Development setup
4 4 ===================
5 5
6 6
7 7 RhodeCode Enterprise runs inside a Nix managed environment. This ensures build
8 8 environment dependencies are correctly declared and installed during setup.
9 9 It also enables atomic upgrades, rollbacks, and multiple instances of RhodeCode
10 10 Enterprise for efficient cluster management.
11 11
12 To set up RhodeCode Enterprise inside the Nix environment use the following steps:
12 To set up RhodeCode Enterprise inside the Nix environment, use the following steps:
13 13
14 14
15 15
16 16 Setup Nix Package Manager
17 17 -------------------------
18 18
19 To install the Nix Package Manager please run::
19 To install the Nix Package Manager, please run::
20 20
21 21 $ curl https://nixos.org/nix/install | sh
22 22
23 or go to https://nixos.org/nix/ and follow their installation instructions.
24 Once this is correctly set up on your system you should be able to use the
23 or go to https://nixos.org/nix/ and follow the installation instructions.
24 Once this is correctly set up on your system, you should be able to use the
25 25 following commands:
26 26
27 27 * `nix-env`
28 28
29 29 * `nix-shell`
30 30
31 31
32 32 .. tip::
33 33
34 34 Update your channels frequently by running ``nix-channel --upgrade``.
35 35
36 36
37 Switch nix to latest STABLE channel
38 -----------------------------------
37 Switch nix to the latest STABLE channel
38 ---------------------------------------
39 39
40 40 run::
41 41
42 42 nix-channel --add https://nixos.org/channels/nixos-16.03 nixpkgs
43 43
44 44 Followed by::
45 45
46 46 nix-channel --update
47 47
48 48
49 49 Clone the required repositories
50 50 -------------------------------
51 51
52 After Nix is set up, clone the RhodeCode Enterprise Community Edition, and
52 After Nix is set up, clone the RhodeCode Enterprise Community Edition and
53 53 RhodeCode VCSServer repositories into the same directory.
54 54 To do this, use the following example::
55 55
56 56 mkdir rhodecode-develop && cd rhodecode-develop
57 57 hg clone https://code.rhodecode.com/rhodecode-enterprise-ce
58 58 hg clone https://code.rhodecode.com/rhodecode-vcsserver
59 59
60 60 .. note::
61 61
62 If you cannot clone the repository, please request read permissions.
62 If you cannot clone the repository, please request read permissions via support@rhodecode.com
63 63
64 64
65 65
66 66 Enter the Development Shell
67 67 ---------------------------
68 68
69 The final step is to start into the development shell. To do this run the
69 The final step is to start the development shell. To do this, run the
70 70 following command from inside the cloned repository::
71 71
72 72 cd ~/rhodecode-enterprise-ce
73 nix-shell --arg dev true
73 nix-shell
74 74
75 75 .. note::
76 76
77 77 On the first run, this will take a while to download and optionally compile
78 a few things. The next runs of it will be faster.
78 a few things. The following runs will be faster.
79 79
80 80
81 81
82 82 Creating a Development Configuration
83 83 ------------------------------------
84 84
85 85 To create a development environment for RhodeCode Enterprise,
86 86 use the following steps:
87 87
88 88 1. Create a copy of `~/rhodecode-enterprise-ce/configs/development.ini`
89 89 2. Adjust the configuration settings to your needs
90 90
91 91 .. note::
92 92
93 It is recommended to call it `dev.ini`.
93 It is recommended to use the name `dev.ini`.
94 94
95 95
96 96 Setup the Development Database
97 97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98 98
99 To create a development database use the following example. This is a one
99 To create a development database, use the following example. This is a one
100 100 time operation::
101 101
102 102 paster setup-rhodecode dev.ini \
103 103 --user=admin --password=secret \
104 104 --email=admin@example.com \
105 105 --repos=~/my_dev_repos
106 106
107 107
108 108 Start the Development Server
109 109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110 110
111 111 When starting the development server, you should start the vcsserver as a
112 separate process. To do this use one of the following examples:
112 separate process. To do this, use one of the following examples:
113 113
114 114 1. Set the `start.vcs_server` flag in the ``dev.ini`` file to true. For example:
115 115
116 116 .. code-block:: python
117 117
118 118 ### VCS CONFIG ###
119 119 ##################
120 120 vcs.start_server = true
121 121 vcs.server = localhost:9900
122 122 vcs.server.log_level = debug
123 123
124 124 Then start the server using the following command: ``rcserver dev.ini``
125 125
126 126 2. Start the development server using the following example::
127 127
128 128 rcserver --with-vcsserver dev.ini
129 129
130 130 3. Start the development server in a different terminal using the following
131 131 example::
132 132
133 133 vcsserver
134 134
135 135
136 136 Run the Environment Tests
137 137 ^^^^^^^^^^^^^^^^^^^^^^^^^
138 138
139 Please make sure that the test are passing to verify that your environment is
139 Please make sure that the tests are passing to verify that your environment is
140 140 set up correctly. More details about the tests are described in:
141 141 :file:`/docs/dev/testing`.
@@ -1,28 +1,28
1 1
2 2
3 3 ============================
4 4 Testing and Specifications
5 5 ============================
6 6
7 7
8 8 .. toctree::
9 9 :maxdepth: 2
10 10
11 11 unit-and-functional
12 12 spec-by-example
13 13 naming-conventions
14 14
15 15
16 16
17 17 Overview
18 18 ========
19 19
20 We have a quite big test suite inside of :file:`rhodecode/tests` which is a mix
20 We have a quite large test suite inside of :file:`rhodecode/tests` which is a mix
21 21 of unit tests and functional or integration tests. More details are in
22 22 :ref:`test-unit-and-functional`.
23 23
24 24
25 Apart from that we start to apply "Specification by Example" and maintain a
26 collection of such specifications together with an implementation so that it can
27 be validated in an automatic way. The files can be found in
25 Apart from that, we are starting to apply "Specification by Example" and maintain
26 a collection of such specifications together with an implementation so that it
27 can be validated in an automatic way. The files can be found in
28 28 :file:`acceptance_tests`. More details are in :ref:`test-spec-by-example`.
@@ -1,75 +1,75
1 1
2 2 .. _test-spec-by-example:
3 3
4 4 ==========================
5 5 Specification by Example
6 6 ==========================
7 7
8 8
9 9 .. Avoid duplicating the quickstart instructions by importing the README
10 10 file.
11 11
12 12 .. include:: ../../../acceptance_tests/README.rst
13 13
14 14
15 15
16 16 Choices of technology and tools
17 17 ===============================
18 18
19 19
20 20 `nix` as runtime environment
21 21 ----------------------------
22 22
23 23 We settled to use the `nix` tools to provide us the needed environment for
24 24 running the tests.
25 25
26 26
27 27
28 28 `Gherkins` as specification language
29 29 ------------------------------------
30 30
31 31 To specify by example, we settled on Gherkins as the semi-formal specification
32 32 language.
33 33
34 34
35 35 `py.test` as a runner
36 36 ---------------------
37 37
38 38 After experimenting with `behave` and `py.test` our choice was `pytest-bdd`
39 39 because it allows us to use our existing knowledge about `py.test` and avoids
40 40 that we have to learn another tool.
41 41
42 42
43 43
44 44 Concepts
45 45 ========
46 46
47 47 The logic is structured around the design pattern of "page objects". The
48 48 documentation of `python-selemium` contains a few more details about this
49 49 pattern.
50 50
51 51
52 52
53 53 Page Objects
54 54 ------------
55 55
56 56 We introduce an abstraction class for every page which we have to interact with
57 57 in order to validate the specifications.
58 58
59 59 The implementation for the page objects is inside of the module
60 60 :mod:`page_objects`. The class :class:`page_objects.base.BasePage` should be
61 61 used as a base for all page object implementations.
62 62
63 63
64 64
65 65 Locators
66 66 --------
67 67
68 68 The specific information how to locate an element inside of the DOM tree of a
69 page is kept in a separate class. This class serves mainly as a data container,
69 page is kept in a separate class. This class serves mainly as a data container;
70 70 it shall not contain any logic.
71 71
72 72 The reason for keeping the locators separate is that we expect a frequent need
73 for change whenever we work on our templates. In such a case it is more
74 efficient to have all locators together and update them there instead of having
75 to find all locators inside of the logic of a page object.
73 for change whenever we work on our templates. In such a case, it is more
74 efficient to have all of thelocators together and update them there instead of
75 having to find every locator inside of the logic of a page object.
@@ -1,61 +1,61
1 1
2 2 .. _test-unit-and-functional:
3 3
4 4 ===========================
5 5 Unit and Functional Tests
6 6 ===========================
7 7
8 8
9 9
10 10 py.test based test suite
11 11 ========================
12 12
13 13
14 14 The test suite is in the folder :file:`rhodecode/tests/` and should be run with
15 15 the test runner `py.test` inside of your `nix-shell` environment::
16 16
17 17 # In case you need the cythonized version
18 18 CYTHONIZE=1 python setup.py develop --prefix=$tmp_path
19 19
20 20 py.test rhodecode
21 21
22 22
23 23
24 24 py.test integration
25 25 -------------------
26 26
27 27 The integration with the test runner is based on the following three parts:
28 28
29 29 - `pytest_pylons` is a py.test plugin which does the integration with the
30 Pylons web framework. It sets up the Pylons environment based on a given ini
30 Pylons web framework. It sets up the Pylons environment based on the given ini
31 31 file.
32 32
33 33 Tests which depend on the Pylons environment to be set up must request the
34 34 fixture `pylonsapp`.
35 35
36 36 - :file:`rhodecode/tests/plugin.py` contains the integration of py.test with
37 37 RhodeCode Enterprise itself.
38 38
39 39 - :file:`conftest.py` plugins are used to provide a special integration for
40 40 certain groups of tests based on the directory location.
41 41
42 42
43 43
44 44 VCS backend selection
45 45 ---------------------
46 46
47 47 The py.test integration provides a parameter `--backends`. It will skip all
48 48 tests which are marked for other backends.
49 49
50 50 To run only Subversion tests::
51 51
52 52 py.test rhodecode --backends=svn
53 53
54 54
55 55
56 56 Frontend / Styling support
57 57 ==========================
58 58
59 59 All relevant style components have an example inside of the "Style" section
60 60 within the application. Enable the setting `debug_style` to make this section
61 61 visible in your local instance of the application.
General Comments 0
You need to be logged in to leave comments. Login now