Traduction of testlink api usage

doc/fr_usage.rst

@@ -0,0 +1,229 @@
+TestLink-API-Python-client Usage
+================================
+
+.. contents::
+   :local:
+
+Comment communiquer avec testlink dans une interface système python
+-------------------------------------------
+
+Se connecter à TestLink, compter les projets existants et récupérer les données d'un cas de test: ::
+
+ [PYENV]\testlink\Scripts\activate
+ set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php
+ set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
+ python
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
+ >>> tls.countProjects()
+ 3
+ >>> tls.getTestCase(None, testcaseexternalid='NPROAPI3-1')
+ [{'full_tc_external_id': 'NPROAPI3-1', 'node_order': '0', 'is_open': '1', 'id': '2757', ...}] 
+
+Demander au TestLink API Client quels arguments attend une des méthodes de l'API: ::
+
+ import testlink
+ tlh = testlink.TestLinkHelper()
+ tls = tlh.connect(testlink.TestlinkAPIClient)
+ print tls.whatArgs('createTestPlan')
+ > createTestPlan(<testplanname>, <testprojectname>, [note=<note>], [active=<active>], 
+                  [public=<public>], [devKey=<devKey>])
+ >  create a test plan 
+
+Générer une description de toutes les méthodes implémentées par l'API: ::
+
+ import testlink
+ tlh = testlink.TestLinkHelper()
+ tls = tlh.connect(testlink.TestlinkAPIClient)
+ for m in testlink.testlinkargs._apiMethodsArgs.keys():
+     print(tls.whatArgs(m), '\n')
+
+Copier les cas de test
+---------------
+
+Copier un cas de test dans une autre suite en changeant son nom::
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
+ >>> tc_info = tls.getTestCase(None, testcaseexternalid='NPROAPI-3')
+ [{'full_tc_external_id': 'NPROAPI-3', ..., 'id': '5440',  'version': '2',  
+   'testsuite_id': '5415', 'tc_external_id': '3','testcase_id': '5425', ...}]
+ >>> tls.copyTCnewTestCase(tc_info[0]['testcase_id'], testsuiteid=newSuiteID, 
+                                          testcasename='a new test case name')
+
+Créer une nouvelle version d'un cas de test en changeant sa description et son importance::  
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
+ >>> tc_info = tls.getTestCase(None, testcaseexternalid='NPROAPI-3')
+ [{'full_tc_external_id': 'NPROAPI-3', ..., 'id': '5440',  'version': '2',  
+   'testsuite_id': '5415', 'tc_external_id': '3','testcase_id': '5425', ...}]
+ >>> tls.copyTCnewVersion(tc_info[0]['testcase_id'], summary='new summary', 
+                                                     importance='1')
+
+
+Par défaut, la dernière version d'un cas de test sera utilisée pour la copie.
+Si une autre version doit être copiée, il est possible de spécifier la version 
+attendue en tant que deuxième argument. Example::
+
+ >>> tls.copyTCnewTestCase(tc_info[0]['testcase_id'], 1, testsuiteid=newSuiteID, 
+                                          testcasename='a new test case name')
+ >>> tls.copyTCnewVersion(tc_info[0]['testcase_id'], 1, summary='new summary', 
+                                                        importance='1')
+
+Rapporter les résultats du test
+-------------------
+
+En utilisant la classe TestlinkAPIClient - exemple d'un cas de test échoué 
+sans auteur (l'argument 'user' n'est utilisable qu'à partir d'une version
+de TestLink de 1.9.10 ou supérieure):
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
+ >>> tls.reportTCResult(a_TestCaseID, a_TestPlanID, 'a build name', 'f', 
+                        'some notes', 
+                        user='a user login name', platformid=a_platformID) 
+
+
+En utilisant la classe TestlinkAPIGeneric - exemple d'un cas de test passé
+en utilisant un auteur (argument 'user'):
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIGeneric)
+  >>> tls.reportTCResult(a_TestPlanID, 'p', testcaseid=a_TestCaseID, 
+                        buildname='a build name', notes='some notes',
+                        user='a login name', platformid=a_platformID) 
+
+
+En utilisant la classe TestlinkAPIGeneric - exemple d'un cas de test bloqué
+sans auteur
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIGeneric)
+ >>> exTCID = tls.getTestCase(testcaseid=a_TestCaseID)[0]['full_tc_external_id']
+ >>> tls.reportTCResult(a_TestPlanID, 'b', testcaseexternalid=exTCID, 
+                        buildid='a build name', platformname='a platform name')
+
+Rapport de résultats de tests avec horodatage et résultat des étapes
+--------------------------------------------------
+
+Ce résultat de test utilise son id externe (testcaseexternalid), et non l'id interne (testcaseid)
+
+-  Les arguments 'execduration' et 'timestamp' requièrent une version de 
+   TestLink de 1.9.14 ou supérieure
+-  L'argument 'steps' requiert une version de TestLink de 1.9.15 ou supérieure
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
+ >>> tls.reportTCResult(None, newTestPlanID_A, None, 'f', '', guess=True,
+                        testcaseexternalid=tc_aa_full_ext_id, platformname=NEWPLATFORM_A,
+                        execduration=3.9, timestamp='2015-09-18 14:33',
+         steps=[{'step_number' : 6, 'result' : 'p', 'notes' : 'result note for passed step 6'}, 
+                {'step_number' : 7, 'result' : 'f', 'notes' : 'result note for failed step 7'}]  )                        
+
+Envoyer des pièces jointes
+------------------
+
+Télécharger des pièces jointes peut être fait de deux différentes manières:
+
+Avec un descripteur de fichier :
+
+ a_file_obj=open(CHEMIN_VALIDE_VERS_LE_FICHIER)
+ newAttachment = myTestLink.uploadExecutionAttachment(a_file_obj, A_Result_ID, 
+                                  'Attachment Title', 'Attachment Description')
+
+
+Ou avec un chemin de fichier :
+
+ a_file_path=A_VALID_FILE_PATH
+ newAttachment = myTestLink.uploadExecutionAttachment(CHEMIN_VALIDE_VERS_LE_FICHIER, A_Result_ID, 
+                                  'Attachment Title', 'Attachment Description')
+
+Lister les mots-clés
+-------------
+
+En utilisant une méthode de l'API (classe TestlinkAPIGeneric) -
+Lister les mots-clés de tous les cas de test d'une suite:
+
+ >>> import testlink
+ >>> tls = testlink.TestLinkHelper().connect(testlink.TestlinkAPIClient)
+ >>> ts_kw = tls.getTestCasesForTestSuite(SuiteID, False, 'full', getkeywords=True)
+
+
+En utilisant une méthode de l'API (classe TestlinkAPIGeneric) -
+Lister tous les mots clés d'une suite de test et ses sous-suites
+
+ >>> ts_kw = tls.getTestCasesForTestSuite(SuiteID, True, 'full', getkeywords=True)
+
+En utilisant une méthode du service (classe TestlinkAPIClient) -
+Lister tous les mots clés sans ses détails pour un cas de test
+
+ >>> tc_kw = tls.listKeywordsForTC(5440)
+ >>> tc_kw = tls.listKeywordsForTC('NPROAPI-3')
+
+En utilisant une méthode du service (classe TestlinkAPIClient) -
+Lister tous les mots clés sans ses détails pour tous les cas de test d'une suite
+
+ >>> ts_kw = tls.listKeywordsForTS('5415')
+
+
+Lancement d'un exemple
+------------
+
+Pour lancer l'exemple "comment utiliser la classe TestlinkAPIClient", en
+spécifiant les paramètres de connexion en tant qu'arguments de ligne de commande [1]_: ::
+
+ [PYENV]\testlink\Scripts\activate
+ python example\TestLinkExample.py 
+                --server_url http://[YOURSERVER]/testlink/lib/api/xmlrpc.php
+                --devKey [Users devKey generated by TestLink]
+
+Pour lancer l'exemple "comment utiliser la classe TestlinkAPIGeneric", en
+spécifiant les paramètres de connexion en tant que variable d'environment [2]_: ::
+
+ [PYENV]\testlink\Scripts\activate
+ set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc/v1/xmlrpc.php
+ set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
+ python example\TestLinkExampleGenericApi.py
+
+.. [1] TestLinkExample.py creates a new test project NEW_PROJECT_API-[CountProjects+1]. 
+.. [2] TestLinkExampleGenericApi.py creates a new test project PROJECT_API_GENERIC-[CountProjects+1]. 
+
+Lancer des tests unitaires
+-------------
+
+Lancer des tests unitaires avec interaction du serveur de TestLink: ::
+
+ [PYENV]\testlink\Scripts\activate
+ set TESTLINK_API_PYTHON_SERVER_URL=http://[YOURSERVER]/testlink/lib/api/xmlrpc.php
+ set TESTLINK_API_PYTHON_DEVKEY=[Users devKey generated by TestLink]
+ cd test\utest
+ python -m unittest discover -s test\utest-online
+
+Lancer des tests unitaires sans interaction du serveur de TestLink: ::
+
+ [PYENV]\testlink\Scripts\activate
+ cd test\utest
+ python -m unittest discover -s test\utest-offline
+
+En deca de Py26, unittest2_ doit être utilisé.  
+
+.. _unittest2: https://pypi.python.org/pypi/unittest2
+
+
+Comment accéder aux données originelles d'échange de XML
+------------------------------------------
+
+Si pour des raisons de débogage les versions originelles d'échange de XML sont requises,
+il est possible d'initialiser l'API client avec le paramètre optionnel *verbose* mis à *True*: ::
+
+ >>> tlh = testlink.TestLinkHelper()
+ >>> tls = testlink.TestlinkAPIClient(tlh._server_url, tl._devkey, verbose=True)
+  send: b"POST /testlink/lib/api/xmlrpc/v1/xmlrpc.php HTTP/1.1\r\nHost: ... 
+        <?xml version='1.0'?>\n<methodCall>\n<methodName>tl.getUserByLogin</methodName>\n<params>...</params>\n</methodCall>\n"
+  reply: 'HTTP/1.1 200 OK\r\n'
+  header: Date header: Server header: ... body: b'<?xml version="1.0"?>\n<methodResponse>\n  <params> ...'
+  body: b'</name><value><string>1</string></value></member>\n</struct></value>\n  <value><struct>\n ...'
+  body: b'...  </params>\n</methodResponse>\n'
+
+