---
name: Create New Session
short_description: Create a new session
description:
  |
    The server should attempt to create a session that most closely matches the desired and required capabilities. 
    
    * [JSONWP Spec](https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#session-1) Required capabilities have higher priority than desired capabilities and must be set for the session to be created
    * [W3C Spec](https://www.w3.org/TR/webdriver/#dfn-new-session) capabilities.alwaysMatch must be set for session to be created; capabilities.firstMatch must match at least one (the first one to match will be used)
    
example_usage:
  java:
    |
        DesiredCapabilities desiredCapabilities = new DesiredCapabilities();
        desiredCapabilities.setCapability(MobileCapabilityType.PLATFORM_VERSION, "10.3");
        desiredCapabilities.setCapability(MobileCapabilityType.DEVICE_NAME, "iPhone Simulator");
        desiredCapabilities.setCapability(MobileCapabilityType.AUTOMATION_NAME, "XCUITest");
        desiredCapabilities.setCapability(MobileCapabilityType.APP, "/path/to/ios/app.zip");

        URL url = new URL("http://127.0.0.1:4723/wd/hub");

        IOSDriver driver = new IOSDriver(url, desiredCapabilities);
        String sessionId = driver.getSessionId().toString();
        
  python:
    |
      desired_caps = desired_caps = {
        'platformName': 'Android',
        'platformVersion': '7.0',
        'deviceName': 'Android Emulator',
        'automationName': 'UiAutomator2',
        'app': PATH('/path/to/app')
      }
      self.driver = webdriver.Remote('http://127.0.0.1:4723/wd/hub', desired_caps)
  javascript_wd:
    |
      let driver = await wd.promiseChainRemote({
        host: '127.0.0.1',
        port: 4723
      });
      let desiredCaps = {
        platformName: 'Android',
        platformVersion: '7.0',
        deviceName: 'Android Emulator',
        app: path.resolve('path', 'to', 'app.apk')
      };
      await driver.init(desiredCaps);

  javascript_wdio:
    |
      let options = { desiredCapabilities: { 
        platformName: 'Android',
        platformVersion: '7.0',
        automationName: 'UiAutomator2',
        app: path.resolve('path', 'to', 'app.apk')
      }};
      let client = webdriverio.remote(options);
  ruby:
    |
      APP_PATH = '../../path/to/app.app'

      desired_caps = {
        caps: {
          platformName:  'iOS',
          platformVersion: '10.2',
          deviceName:    'iPhone 6',
          app:           APP_PATH,
          automationName: "XCUITest"
        }
      }

      Appium::Driver.new(desired_caps).start_driver
  php:
    |
      // TODO PHP sample
  csharp:
    |
      // TODO C# sample

client_docs:
  java: "https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/remote/server/DefaultSession.html#createSession-org.openqa.selenium.remote.server.DriverFactory-org.openqa.selenium.remote.server.Clock-org.openqa.selenium.remote.SessionId-org.openqa.selenium.Capabilities-"
  python: "http://selenium-python.readthedocs.io/api.html#selenium.webdriver.remote.webelement.WebElement.clear"
  javascript_wdio: "http://webdriver.io/api/action/clearElement.html"
  javascript_wd: "https://github.com/admc/wd/blob/master/lib/commands.js#L1780"
  ruby: "http://www.rubydoc.info/gems/selenium-webdriver/Selenium/WebDriver/Element:clear"
  php: "https://github.com/appium/php-client/" # TODO PHP documentation link
  csharp: "https://github.com/appium/appium-dotnet-driver/" # TODO Dotnet documentation link

# Driver support by platform
driver_support:
  ios:
    xcuitest: true
    uiautomation: true
  android:
    uiautomator2: true
    uiautomator: true
  mac:
    mac: true
  windows:
    windows: true
client_support:
  java: true
  python: true
  ruby: true
  php: true
  csharp: true
  javascript_wd: true
  javascript_wdio: true
  

# Information about the HTTP endpoints
endpoint:
  url: /session
  method: POST
  json_parameters:
    - name: desiredCapabilities
      type: object
      description: ([JSONWP specification](https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#session-1)) Object describing session's [desired capabilities](/docs/en/writing-running-appium/caps.md)
    - name: requiredCapabilities
      type: object
      description: ([JSONWP specification](https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#session-1)) Object describing session's required capabilities that must be applied by remote end
    - name: capabilities
      type: object
      description: ([W3C specification](https://www.w3.org/TR/webdriver/#dfn-new-session)) object containing 'alwaysMatch' and 'firstMatch' properties
    - name: capabilities.alwaysMatch
      type: object
      description: The [desired capabilities](/docs/en/writing-running-appium/caps.md) that the remote end must match
    - name: capabilities.firstMatch
      type: array<object>
      description: List of capabilities that the remote end tries to match. Matches the first in the list
  response:
    - type: object
      description: An object describing the session's capabilities

# Links to specifications. Should link to at least one specification
specifications: 
  w3c: https://www.w3.org/TR/webdriver/#dfn-new-session
  jsonwp: https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#session-1