APIs for starting a test session

[SuperAlokB]

I am looking for api list to post - sessions id - want to execute appium test cases directly from code

[adrianth]

We are in the process of documenting the APIs on the website, but I'll try to do explain it briefly here. The OpenTest server exposes two APIs that can be used to start a test session:

API 1: Create a session passing the list of tests

POST http://localhost:3000/api/session

The body of this POST request looks like this:

{
    "actorTags": [],
    "environment": "",
    "maxIterations": "1",
    "sessionLabel": "My session",
    "tests": [
        {
            "name": "Test 1",
            "path": ""
        }, {
            "name": "Test 2",
            "path": ""
        }
    ]
}

All the properties in the JSON payload are mirroring the details you are passing when you start a test session from the OpenTest server UI.
You can ignore the actorTags property, unless you need to target a specific actor when running your session (if you are not sure, then you most probably don't). The environment property can be empty, if you are not using the environments feature. maxIterations is the number of times to retry the execution of a failed test (this is to alleviate the problem of flaky, non-deterministic tests). The tests array is an array of objects that represent the name of the YAML file with the test and its path, relative to the tests directory. If the test is in the tests directory (and not in a subdirectory), then the path property can be left empty, like in the example above.

API 2: Create a session from a template

This API allows you to start a test session based on a test session template file, that you have already prepared and saved in the test-repo/templates directory (more details below).

POST http://localhost:3000/api/session/from-template

The body of this POST request looks like this:

{
    "template": {
        "name": "smoke-tests",
        "path": ""
    }
}

Session template files are YAML files that describe the details of a test session (the same ones I already talked about: the list of tests, the environment etc.). Here's an example:

description: Runs the sample tests that don't require any configuration
sessionLabel: Quick start tests
maxIterations: 1
tests:
    - name: GitHub API test
      path: api
 
    - name: Using an external JavaScript file
      path: other

You can take a look in the templates directory created by the opentest quick-start command to get a better idea of how the whole setup looks like.

If you want to integrate OpenTest in a CI pipeline, you can use one of these APIs to kick off a test session. The second API is better, because it doesn't require you to specify the full lists of tests in the API call. You can use a tool like curl to make the API call, something like this:

curl -H "Content-Type: application/json" -d "{\"template\": {\"name\": \"smoke-tests\", \"path\": \"/\"}}" http://localhost:3000/api/session/from-template

We are in the process of adding some new command-line options to make this process even easier, which will probably be delivered beginning of August.

[joannalaine]

Hi @adrianth,
When creating a session from a template using /api/session/from-template, is it possible to edit any of the session details? I would like to use a template that has been created and is maintained by someone else, so I want to avoid editing the template directly or creating another copy of the template.
For example, for the template "smoke-tests," I'd like to edit the sessionLabel to "smoke-tests v5.17_200" to reflect the build number I'm running on, so that when I look at my dashboard, I can tell my sessions apart. Also, within that template, the maxIterations is 2, and I'd like to change it to 1.
Thanks,
Joanna

[adrianth]

@joannalaine Unfortunately, this is not possible just yet, but some other team had some similar requests and this feature will be available in the next OpenTest release. I will add a comment to this issue with the details, when it becomes available.

[adrianth]

Hey @joannalaine, starting with version 1.0.4, we support starting a session from a template file and overriding the properties in the template by using the "create session" API call (POST /api/session). See more details in the docs: https://getopentest.org/reference/web-api.html#creating-a-test-session.

This renders the POST /api/session/from-template API unnecessary, but we are keeping it for now, for backward compatibility.

Please note that version 1.0.4 works with Appium 1.8.0 or later. It will also work with previous versions, with a small caveat: the iOS swiping in Appium 1.7.X is relative to the position of the element being swiped, whereas in 1.8.X it is defined in absolute screen coordinates, so you'll see some issues there. This can be fixed by upgrading Appium to the latest version (preferred) or by using the appium.useRelativeCoordsIos parameter and actor.yaml with a value of true.

Let me know if you have any questions.

[joannalaine]

Hi @adrianth, I finally got a chance to try this out for both templates and individual tests. It works great! Thanks for new utility!

[reinaldo-dias]

@adrianth --It works pretty good....I could invoke / integrate opentest in my deployment scripts using curl. Thanks a lot!
Reinaldo

[adrianth]

Hi @reinaldo-dias. Glad to hear you were able to make good use of the updated API.

[johnnydutra]

Hi @adrianth
Nice job with the framework!

We're applying CI integration over here and there's question we couldn't find an answer to.

Is it possible to call a template with curl and change the session label with a variable?

Our goal is to print the current application build as the session label when executing the tests in a template.

We've tried this:

curl -H "Content-Type: application/json" -d "{"sessionLabel": $build, "template": {"name": "SmokeTest", "path": "/"}}" http://testurlhere

When running it this way, the label given to the session is a copy of its id number.

What could be done differently to make it work?

Thanks in advance.

[adrianth]

Hi @johnnydutra, the OpenTest server will use the session ID as the session label if:

• It cannot find a custom session label in the payload of the API call.
• It cannot find a custom session label in the session template you specified in the API call.

It looks like your "SmokeTest" template doesn't contain a session label property and the $build variable doesn't contain a value either (or you're not running the latest OpenTest version).

Please make sure that you are using the latest version of OpenTest (customizing the session label in the API call was not possible before v1.0.4), and check that your $build variable really contains a value. For troubleshooting purposes, you could try to hardcode the session label in the curl command line, to confirm that the label is correctly assigned by the OpenTest server.

[johnnydutra]

Hello @adrianth,

We ran some tests following the inputs you provided there, but still couldn't make it happen.
However, we were calling the "from-template" API. When we switched it to the regular /api/session one, it worked fine.

Thanks for the support.

[adrianth]

Oh, I understand now. I had assumed you were using the /api/session API,since you didn't specify the URL in your curl command example. Sorry, I should have mentioned the API too. The "from-template" API is deprecated now that the /api/session API can do the same thing (and more).