Skip to content

Commit f0c5617

Browse files
author
Luiko Czub
committed
install and usage documentation extracted from readme.md #15
although unit test directory split into two directories * utest-offline - unit test not interacting with TestLink * utest-online - unit test interacting with TestLink
1 parent c5d90a8 commit f0c5617

13 files changed

+209
-3
lines changed

‎MANIFEST.in

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ recursive-include src *.py
33
recursive-include example *.py
44
recursive-include example *.png
55
recursive-include test *.py
6+
recursive-include doc *.rst

‎README.md

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,20 +21,31 @@ TestLink-API-Python-client delivers two main classes
2121
- TestlinkAPIClient - Inherits from TestlinkAPIGeneric and defines service
2222
methods like "countProjects".
2323

24+
and the helper class
25+
26+
- TestLinkHelper - search connection parameter from environment variables and
27+
command line arguments
28+
2429
Directory Layout
2530
----------------
2631

2732
src/
2833

2934
* Source for TestLink API Python Client
3035

31-
tests/
36+
doc/
3237

33-
* Unit Tests for TestLink API Python Client
38+
* [Installation] and [Usage] documentation
3439

3540
examples/
3641

37-
* Examples, how to use the TestLink API Python Client
42+
* Examples, how to use [TestlinkAPIGeneric] and [TestlinkAPIClient].
43+
* For (nearly all) implemented API methods you find an example, how to call
44+
it and how the response looks like.
45+
46+
tests/
47+
48+
* Unit Tests for TestLink API Python Client
3849

3950
Installation
4051
------------
@@ -163,6 +174,10 @@ TestLink-API-Python-client developers
163174
[Robot Framework]: http://code.google.com/p/robotframework
164175
[Jenkins]: http://jenkins-ci.org/
165176
[Releases]: https://github.com/lczub/TestLink-API-Python-client/releases
177+
[Installation]: doc/install.rst
178+
[Usage]: doc/usage.rst
179+
[TestlinkAPIGeneric]: example/TestLinkExampleGenericApi.py
180+
[TestlinkAPIClient]: example/TestLinkExample.py
166181
[SourceForge]: http://sourceforge.net/projects/testlink-api-python-client/files/latest/download
167182
[Issues]: https://github.com/lczub/TestLink-API-Python-client/issues
168183
[Olivier Renault]: https://github.com/orenault/TestLink-API-Python-client

‎doc/install.rst

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
TestLink-API-Python-client Installation
2+
=======================================
3+
4+
Preconditions
5+
-------------
6+
7+
Currently only the combination Python 2.7 and TestLink 1.9.8/1.9.9 is tested.
8+
Other combination might work - feedback is welcome :-)
9+
10+
TestLink configuration
11+
----------------------
12+
13+
The TestLink configuration (config.inc.php or custom_config.inc.php) must have
14+
enabled the api interface
15+
16+
$tlCfg->api->enabled = TRUE;
17+
18+
Create the user specific devKey inside TestLink, see
19+
20+
- My Settings -> API interface - Personal API access key [Generate a new key]
21+
22+
Installing from PyPI
23+
--------------------
24+
25+
TestLink-API-Python-client will be available in the Python Package Index (PyPI_)
26+
with Release v0.4.6. It is recommended that you use `pip`_ to install.
27+
28+
Install from PyPI using pip by running::
29+
30+
pip install TestLink-API-Python-client
31+
32+
Installing from source distribution
33+
-----------------------------------
34+
35+
The source code can be retrieved as source distribution either
36+
37+
- as stable release from SourceForge_
38+
- or as development version from `GitHup Releases`_
39+
40+
Install the archives using pip by running::
41+
42+
pip install TestLink-0.4.6.zip
43+
44+
Installing from source
45+
----------------------
46+
47+
Install the extracted source distribution or download of the last (none tested)
48+
changes from `GitHup Master`_ by running::
49+
50+
python setup.py install
51+
52+
Verifying Installation
53+
----------------------
54+
55+
Check, if Python could talk with TestLink using the connection parameter
56+
57+
- SERVER_URL = 'http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php'
58+
- DEVKEY = '[Users devKey generated by TestLink]'
59+
60+
as init parameter::
61+
62+
python
63+
>>> import testlink
64+
>>> tls = testlink.TestlinkAPIClient(SERVER_URL, DEVKEY)
65+
>>> tls.about()
66+
' Testlink API Version: 1.0 initially ....'
67+
68+
or by defining the connection parameter as environment variables::
69+
70+
set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php
71+
set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
72+
python
73+
>>> import testlink
74+
>>> tls = testlink.TestLinkHelper(testlink.TestlinkAPIClient)
75+
>>> tls.about()
76+
' Testlink API Version: 1.0 initially ....'
77+
78+
Changed SERVER_URL with TestLink 1.9.7
79+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
81+
The SERVER_URL path has changed with TestLink 1.9.7.
82+
83+
- TL Version < 1.9.7: Use http://[YOURSERVER]/testlink/lib/api/xmlrpc.php
84+
- TL Version =>1.9.7: Use http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php
85+
86+
Install in virtualenv TestLink
87+
------------------------------
88+
89+
Cause most linux system (and although newer windows systems too) expect root
90+
privileges for installation, a separate TestLink virtualenv_ may help::
91+
92+
[PYTHON27]\Scripts\virtualenv [PYENV]\testlink
93+
[PYENV]\testlink\Scripts\activate
94+
pip install TestLink-API-Python-client
95+
96+
If you always work with the same TestLink server, extend the script
97+
98+
- [PYENV]\testlink\Scripts\activate.
99+
100+
with connection parameter as environment variables
101+
102+
- TESTLINK_API_PYTHON_SERVER_URL and TESTLINK_API_PYTHON_DEVKEY
103+
104+
105+
106+
.. _PyPI: https://pypi.python.org/pypi
107+
.. _pip: http://www.pip-installer.org
108+
.. _SourceForge: http://sourceforge.net/projects/testlink-api-python-client/files/latest/download
109+
.. _GitHup Releases: https://github.com/lczub/TestLink-API-Python-client/releases
110+
.. _GitHup Master: https://github.com/lczub/TestLink-API-Python-client/archive/master.zip
111+
.. _virtualenv: http://www.virtualenv.org/en/latest/virtualenv.html

‎doc/usage.rst

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
TestLink-API-Python-client Usage
2+
================================
3+
4+
How to talk with TestLink in a python shell
5+
-------------------------------------------
6+
7+
Connect TestLink, count existing projects and get test case data: ::
8+
9+
[PYENV]\testlink\Scripts\activate
10+
set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php
11+
set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
12+
python
13+
>>> import testlink
14+
>>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
15+
>>> tls.countProjects()
16+
3
17+
>>> tls.getTestCase(None, testcaseexternalid='NPROAPI3-1')
18+
[{'full_tc_external_id': 'NPROAPI3-1', 'node_order': '0', 'is_open': '1', 'id': '2757', ...}]
19+
20+
Ask the TestLink API Client, what arguments a API method expects: ::
21+
22+
import testlink
23+
tlh = testlink.TestLinkHelper()
24+
tls = tlh.connect(testlink.TestlinkAPIClient)
25+
print tls.whatArgs('createTestPlan')
26+
> createTestPlan(<testplanname>, <testprojectname>, [note=<note>], [active=<active>], [public=<public>], [devKey=<devKey>])
27+
> create a test plan
28+
29+
or generate a description of all implemented API method: ::
30+
31+
import testlink
32+
tlh = testlink.TestLinkHelper()
33+
tls = tlh.connect(testlink.TestlinkAPIClient)
34+
for m in testlink.testlinkargs._apiMethodsArgs.keys():
35+
print tls.whatArgs(m), '\n'
36+
37+
38+
Run Examples
39+
------------
40+
41+
Running example [#]_, how to use the class TestlinkAPIClient, with connection
42+
parameter defined as command line arguments: ::
43+
44+
[PYENV]\testlink\Scripts\activate
45+
python example\TestLinkExample.py
46+
--server_url http://[YOURSERVER]/testlink/lib/api/xmlrpc.php
47+
--devKey [Users devKey generated by TestLink]
48+
49+
Running example [#]_, how to use the class TestlinkAPIGeneric, with connection
50+
parameter defined as environment variables: ::
51+
52+
[PYENV]\testlink\Scripts\activate
53+
set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php
54+
set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
55+
python example\TestLinkExampleGenericApi.py
56+
57+
Run unittests
58+
-------------
59+
60+
Run unittests with TestLink Server interaction: ::
61+
62+
[PYENV]\testlink\Scripts\activate
63+
set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc.php
64+
set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
65+
cd test\utest
66+
python -m unittest discover -s test\utest-online
67+
68+
Run unittests without TestLink Server interaction: ::
69+
70+
[PYENV]\testlink\Scripts\activate
71+
cd test\utest
72+
python -m unittest discover -s test\utest-offline
73+
74+
.. [#] TestLinkExample.py creates a new test project NEW_PROJECT_API-[CountProjects+1].
75+
.. [#] TestLinkExampleGenericApi.py creates a new test project PROJECT_API_GENERIC-[CountProjects+1].

‎setup.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,10 @@
5050
3
5151
>>> tls.getTestCase(None, testcaseexternalid='NPROAPI3-1')
5252
[{'full_tc_external_id': 'NPROAPI3-1', 'node_order': '0', 'is_open': '1', 'id': '2757', ...}]
53+
>>> print tls.whatArgs('createTestPlan')
54+
createTestPlan(<testplanname>, <testprojectname>, [note=<note>], [active=<active>], [public=<public>], [devKey=<devKey>])
55+
create a test plan
56+
5357
5458
More information about this library can be found on the Wiki_
5559

‎test/utest/testlinkapi_offline_test.py renamed to ‎test/utest-offline/testlinkapi_offline_test.py

File renamed without changes.

‎test/utest/testlinkapigeneric_offline_test.py renamed to ‎test/utest-offline/testlinkapigeneric_offline_test.py

File renamed without changes.

‎test/utest/testlinkargstest.py renamed to ‎test/utest-offline/testlinkargstest.py

File renamed without changes.

‎test/utest/testlinkdecoratorstest.py renamed to ‎test/utest-offline/testlinkdecoratorstest.py

File renamed without changes.

‎test/utest/testlinkhelpertest.py renamed to ‎test/utest-offline/testlinkhelpertest.py

File renamed without changes.

0 commit comments

Comments
 (0)