Skip to content

Commit

Permalink
intro doc update
Browse files Browse the repository at this point in the history
  • Loading branch information
Jonahss committed Jul 7, 2014
1 parent ea16247 commit b4cbfac
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 38 deletions.
3 changes: 2 additions & 1 deletion docs/en/about-appium/appium-clients.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@ Appium client libraries implement the [Mobile JsonWire Protocol](https://code.go

Appium client libraries only **add** functionality, so they can still be used to run regular Selenium sessions.

Language | Github Repo and Installation Instructions |
Language/Framework | Github Repo and Installation Instructions |
----- | ----- |
Ruby | [https://github.com/appium/ruby_lib](https://github.com/appium/ruby_lib)
Python | [https://github.com/appium/python-client](https://github.com/appium/python-client)
Java | [https://github.com/appium/java-client](https://github.com/appium/java-client)
JavaScript (Node.js) | [https://github.com/admc/wd](https://github.com/admc/wd)
PHP | [https://github.com/appium/php-client](https://github.com/appium/php-client)
C# (.NET) | [https://github.com/appium/appium-dotnet-driver](https://github.com/appium/appium-dotnet-driver)
RobotFramework | [https://github.com/jollychang/robotframework-appiumlibrary](https://github.com/jollychang/robotframework-appiumlibrary)
61 changes: 24 additions & 37 deletions docs/en/about-appium/intro.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,35 @@
## Introduction to Appium

Appium is an open-source tool you can use to automate mobile native,
mobile web, and mobile hybrid applications on iOS and Android platforms.
"Mobile native apps" are those written using the iOS or Android SDKs. "Mobile
web apps" are web apps accessed using a mobile browser (Appium supports
Safari on iOS and Chrome on Android). "Mobile hybrid apps" have a native
Appium is an open-source tool for automating native,
mobile web, and hybrid applications on iOS and Android platforms.
**Native apps** are those written using the iOS or Android SDKs. **Mobile web apps** are web apps accessed using a mobile browser (Appium supports
Safari on iOS and Chrome on Android). **Hybrid apps** have a
wrapper around a "webview" -- a native control that enables interaction with
web content. Projects like [Phonegap](http://phonegap.com/), for example,
web content. Projects like [Phonegap](http://phonegap.com/),
make it easy to build apps using web technologies that are then bundled into
a native wrapper -- these are hybrid apps.
a native wrapper, creating a hybrid app.

Importantly, Appium is "cross-platform": it allows you to write tests against
multiple platforms (iOS, Android), using the same API. This enables a large
or total amount of code reuse between iOS and Android testsuites.
multiple platforms (iOS, Android), using the same API. This enables code reuse between iOS and Android testsuites.

For specific information about what it means for Appium to "support" its
platforms, version, and automation modalities, please see the [platform support doc](platform-support.md).
platforms, and automation modalities, please see the [platform support doc](/docs/en/appium-setup/platform-support.md).

### Appium Philosophy

Appium was designed to meet mobile automation needs according to a certain
philosophy. The key points of this philosophy can be stated as 4 requirements:
Appium was designed to meet mobile automation needs according to a philosophy outlined by the following four tenets:

1. You shouldn't have to recompile your app or modify it in any way in order
to automate it.
2. You shouldn't be locked into a specific language or framework to write and
run your tests.
3. A mobile automation framework shouldn't reinvent the wheel when it comes
to automation APIs.
4. A mobile automation framework should be open source,
in spirit and practice as well as in name!
1. You shouldn't have to recompile your app or modify it in any way in order to automate it.
2. You shouldn't be locked into a specific language or framework to write and run your tests.
3. A mobile automation framework shouldn't reinvent the wheel when it comes to automation APIs.
4. A mobile automation framework should be open source, in spirit and practice as well as in name!

### Appium Design

So how does the structure of the Appium project live out this philosophy? We
meet requirement #1 by using vendor-provided automation frameworks under the
hood. That way, we don't need to compile in any Appium-specific or
third-party code or frameworks to your app. This means you're testing the
same app you're shipping. The vendor-provided frameworks we use are:
third-party code or frameworks to your app. This means **you're testing the same app you're shipping**. The vendor-provided frameworks we use are:

* iOS: Apple's [UIAutomation](https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/_index.html)
* Android 4.2+: Google's [UiAutomator](http://developer.android.com/tools/help/uiautomator/index.html)
Expand All @@ -49,7 +41,7 @@ WebDriver (aka "Selenium WebDriver") specifies a client-server protocol
(known as the [JSON Wire Protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol)).
Given this client-server architecture, a client written in any language can
be used to send the appropriate HTTP requests to the server. There are
already clients written in every popular programming language. This also
already [clients written in every popular programming language](http://appium.io/downloads). This also
means that you're free to use whatever test runner and test framework you
want; the client libraries are simply HTTP clients and can be mixed into your
code any way you please. In other words, Appium & WebDriver clients are not
Expand All @@ -72,8 +64,8 @@ connections from a client, listens for commands, executes those commands on a
mobile device, and responds with an HTTP response representing the result of
the command execution. The fact that we have a client/server architecture
opens up a lot of possibilities: we can write our test code in any language
that has a http client API, but it is easier to use one of the Appium client
library. We can put the server on a different machine than our
that has a http client API, but it is easier to use one of the [Appium client
libraries](http://appium.io/downloads). We can put the server on a different machine than our
tests are running on. We can write test code and rely on a cloud service
like [Sauce Labs](https://saucelabs.com/mobile) to receive and interpret the commands.

Expand All @@ -83,39 +75,34 @@ a session with a server in ways specific to each library,
but they all end up sending a `POST /session` request to the server,
with a JSON object called the 'desired capabilities' object. At this point
the server will start up the automation session and respond with a session ID
which can be used in sending further commands.
which is used for sending further commands.

**Desired Capabilities**<br/>
Desired capabilities are sets of keys and values (i.e.,
Desired capabilities are a set of keys and values (i.e.,
a map or hash) sent to the Appium server to tell the server what kind of
automation session we're interested in starting up. There are also various
capabilities which can modify the behavior of the server during automation.
For example, we might set the `platformName` capability to `iOS` to tell
Appium that we want an iOS session, rather than an Android one. Or we might
set the `safariAllowPopups` capability to `true` in order to ensure that,
during a Safari automation session, we're allowed to use JavaScript to open
up new windows. See the [capabilities doc](caps.md) for the complete list of
capabilities available for Appium.
up new windows. See the [capabilities doc](/docs/en/writing-running-appium/caps.md) for the complete list of capabilities available for Appium.

**Appium Server**<br/>
Appium is a server written in Node.js. It can be built and installed from
source or directly from NPM.
Appium is a server written in Node.js. It can be built and installed from source or installed directly from NPM.

**Appium Clients**<br/>
There are client libraries (in Java, Ruby, Python, PHP, JavaScript, and C#)
which support Appium's extensions to the WebDriver protocol. When using Appium,
you want to use these client libraries instead of your regular WebDriver
client. You can view the full list of libraries [here](appium-clients.md).
client. You can view the full list of libraries [here](/appium-clients.md).

**[Appium.app](https://github.com/appium/appium-dot-app), [Appium.exe](https://github.com/appium/appium-dot-exe)**<br/>
There exist GUI wrappers around the Appium server that can be downloaded.
These come bundled with everything required to run the Appium server,
so you don't need to worry about Node. They also come with an Inspector,
which enables you to check out the hierarchy of your app. This can come in
very handy when writing tests!
which enables you to check out the hierarchy of your app. This can come in handy when writing tests.

### Getting Started

Congratulations! You are now armed with enough knowledge to begin using
Appium. Why not head back to the [getting started doc](../../README.md) for
more detailed requirements and instructions?
Congratulations! You are now armed with enough knowledge to begin using Appium. Why not head to the [getting started doc](/README.md) for more detailed requirements and instructions?

0 comments on commit b4cbfac

Please sign in to comment.