DEV Community: Moe Monfared

Test Independence Done Right: How to write truly isolated tests!

Moe Monfared — Sat, 03 May 2025 15:43:19 +0000

Overview

One of the MOST important rules in automation is having independent tests. This means tests should not rely on each other and you should be able to run any test from any suite at any time.

In this blog post, I am sharing some proven practices I've picked up over a decade in test automation. Cypress is used for the demos, but the concepts apply to any test automation stack.

Special thanks to @Sebastian Clavijo Suero for his great feedback and suggestions!

⚠️ Disclaimer: The techniques and practices shared in this article are based on real-world experience across multiple projects and teams. While they’ve worked well for me and many others, they’re not the only way to approach test isolation, and I’m not claiming these are the best approaches. There may be different valid solutions depending on your tech stack or infrastructure.

The Problem

Let’s look at an example of a simple API CRUD (Create, Read, Update, and Delete) test for a project entity in a sample application. Here are the available requests for its endpoint.

POST /project > Create a new project
GET /project/:id > Returns all projects
PUT /project/:id > Update the project with projectId
DELETE /project/:id > Delete the project with projectId

You might write something like this:

describe('CRUD Tests for /project', () => {
  let project;

  it('Should create a project', () => {
    cy.request('POST', '/project', { name: 'An Awesome Project' })
      .then((res) => {
        project = res.body;
      });
  });

  it('Should read a project', () => {
    cy.request('GET', `/project/${project.id}`).its('body.name')  // assumes a project already exists 🤨
      .should('include', 'Awesome');
  });

  it('Should update a project', () => {
    cy.request('PUT', `/project/${project.id}`, { name: 'Updated Project' });
    cy.request('GET', `/project/${project.id}`).its('body.name')
      .should('eq', 'Updated Project');
  });

  it('Should delete a project', () => {
    cy.request('DELETE', `/project/${project.id}`);
    cy.request({
      method: 'GET',
      url: `/project/${project.id}`,
      failOnStatusCode: false
    }).its('status').should('eq', 404);
  });
});

Looks simple, hah? It seems all tests pass even when running this code multiple times.

But what happens if the first test fails? ❌ The other tests fail too because the project is undefined (we’re relying on the first test to create a project).
Can you run the update test by putting the .only annotation? ❌ No! Because there is no project to update!

Ok, Why do we need to solve this problem?

No dependency on previous tests
No test order dependency
Clean environment for every test (no leftovers from previous tests)
Easier debugging
Less flaky tests
Parallel execution

Side note: Environment Isolation

In this article, we are focusing on isolated tests, not environments. However, It’s worth to mentioning this distinction.

Consider this scenario: You have a project-crud.cy.js test file. You want to run this on your local machine, you colleague is manually testing project creation, and 3 parallelized machines in CI are going to run the same test as a scheduled run; all in the same environment ( and even worse with the same user credentials).

Is it feasible? It’s like multiple people trying to drive the same car at the same time! This definitely prevents automation feasibility at all. So what are some solutions to resolve this issue?

Create a new fresh environment (known as Ephemeral environments) for each test run, with a new deployment of the latest backend plus a pre-created database snapshot
Using a mock server to completely bypass the backend. (Applicable for UI functional tests and required frontend project to build and run locally)
Use separate test users (Multi-Tenancy)
Use unique test data for each test
etc.

Hooks:

Before discussing test isolation/independence techniques, let’s understand the different test run stages (known as hooks in the JavaScript world). Beyond the actual test, we need separate stages to set up preconditions and clean up afterward. Here are all the available hooks in Mocha and Cypress:

it(): Test block where the actual test steps are defined
specify(): Just an alias for it() block. Behaves the same. However It is rarely used.
describe(): Where we organize test cases based on features or modules. Known as Test Suite.
context(): Just an alias for describe(), used when grouping tests based on conditions (or/and) with nested describe blocks.
before(): It runs once before the test suite (describe or context). Known as Suite Setup.
beforeEach(): It runs before each test. Known as Test Setup
after(): Runs one time after the test suite. Known as Suite Teardown
afterEach: It runs after each test. Known as Test Teardown

To run something before everything else in cypress, place it in before() hooks within cypress/support/e2e.js, as this file runs during Cypress initialization.

Scope

When mixing and nesting hooks, be mindful of their scopes. The more outer scope is, the broader its effect. To understand it better, try to run this test file in cypress and check the sequence of actual cypress logs!

➡️ Nesting and complicating test files is usually a bad practice and this example is just for learning purposes only.

// Root level hooks
before( () => {
    cy.log('Root level suite SETUP')
})
after( () => {
    cy.log('Root level suite TEARDOWN')
})
beforeEach(() => {
    cy.log('Root level test SETUP')
})
afterEach(() => {
    cy.log('Root level test TEARDOWN')
})

describe('Describe Block1', () => {
    before( () => {
        cy.log('Run BEFORE describe block1')
    })
    after( () => {
        cy.log('Run AFTER describe block1')
    })
    beforeEach(() => {
        cy.log('Test SETUP1')
    })
    afterEach(() => {
        cy.log('Test TEARDOWN1')
    })


    it('Test 1 inside Describe Block1', () => {
        cy.log('Test 1 inside Describe Block1')
    })
    it('Test 2 inside Describe Block1', () => {
        cy.log('Test 2 inside Describe Block1')
    })

})

describe('Describe Block2', () => {
    before( () => {
        cy.log('Run BEFORE describe block2')
    })
    after( () => {
        cy.log('Run AFTER describe block2')
    })
    beforeEach(() => {
        cy.log('Test SETUP2')
    })
    afterEach(() => {
        cy.log('Test TEARDOWN2')
    })


    it('Test 1 inside Describe Block2', () => {
        cy.log('Test 1 inside Describe Block2')
    })
    it('Test 2 inside Describe Block2', () => {
        cy.log('Test 2 inside Describe Block2')
    })

    context('Context Block1', () => {
        it('Test 1 inside Context Block1 which is inside Describe Block2', () => {
            cy.log('Test 1 inside Context Block1')
        })

    })
})

context('Context Block2', () => {
    specify('Test 1 inside Context Block2', () => {
        cy.log('Test 1 inside Context Block2')
    })

})

Here’s how it all runs together:

AAA pattern in test automation:

A standard automation test has three main stages:

Arrange: Everything you should do to prepare the environment for testing. For example logging in, creating required resources, cleaning up previous tests' leftovers, etc.
Act: The actual test steps that interact with our application.
Assert: Verify the application's expected behavior and reactions to Act interactions.

➡️ The Arrange is done inside the Setup stage, while the Act and Assert are done together during the test stage.

Keep this in mind since we will reference it again. Now let’s talk about the interesting part!

Now let's see in action: How to make tests independent?

It actually requires us to implement these minimum techniques:

1. Using Setup and Teardown

2. Use dynamic singleton variables - file-scoped or framework-scoped

3. Use random data (string/UUIDs, etc. )

1. Setup / Teardown

Setup: Initial actions taken before a test suite or individual test case runs, ensuring a clean and prepared environment for testing. As mentioned in Hooks, we use before() and beforeEach() for this.

Teardown: Cleans up resources and resets the environment to its original state after the test case completes. In Mocha (Cypress), after() and afterEach() handle this.

➡️ Teardown stages always run regardless of test status (fail/pass).

Let’s come back to our initial example of CRUD operation on the project entity. So in order to make tests independent, we should create a dedicated project for each test and then delete it after the test; right?

Here’s how we can use setup/teardown hooks to achieve this:

describe('CRUD Tests for /project', () => {
  let project;

  beforeEach('Create a project before each test', () => {
  // Arrange
    cy.request('POST', '/project', { name: 'An Awesome Project' })
      .then((res) => {
        project = res.body;
      });
  })

  afterEach('Delete the project after each test', () => {
  cy.request('DELETE', `/project/${project.id}`)
    .then((res) => {
        expect(res.status).to.eq(200) 
      });
  })

  it('Should create a project', () => {
  // Act
    cy.request('POST', '/project', { name: 'An Awesome Project' })
      .then((res) => {
        project = res.body;

        // Assert
        expect(res.status).to.eq(201) 
      });
  });

  it('Should read a project', () => {
  // Act and Assert
    cy.request('GET', `/project/${project.id}`).its('body.name') 
      .should('include', 'Awesome');
  });

  it('Should update a project', () => {
  // Act and Assert
    cy.request('PUT', `/project/${project.id}`, { name: 'Updated Project' })
      .then((res) => {
        expect(res.status).to.eq(201) 
      });
    cy.request('GET', `/project/${project.id}`).its('body.name')
      .should('eq', 'Updated Project');
  });

  it('Should delete a project', () => {
  // Act and Assert
    cy.request('DELETE', `/project/${project.id}`)
    .then((res) => {
        expect(res.status).to.eq(200) 
      });
    cy.request({
      method: 'GET',
      url: `/project/${project.id}`,
      failOnStatusCode: false
    }).its('status').should('eq', 404);
  });
});

Better now; each test has its own project in place and deletes it afterward.
But can we make it better somehow? Do you spot any repeating for example?

Following are some points to consider:

The CREATE test itself (first one) doesn’t need a project created in setup, since it tests the actual project creation functionality. So we should find a way to run the setup stage conditionally. This is where context helps us separate tests based on conditions.
It seems like we are repeating the CREATE operation in each test setup! Well, actually it is correct, but here is one of the trade-offs in test automation world. Having some repeats to make tests independent is acceptable (when we can't use solutions like separate environments or database snapshots). We need a fresh project (and other environment values) each time if we want to reach the goal of independence. But then what is the difference between CREATE in setup versus CREATE in test? The answer is; the first one (test setup) doesn't include Assert.
Teardown in Setup: Yes, that is correct. As a good practice in test automation, we should do as much as we can in Test Setup, instead of Teardown. For example deleting the created projects (test leftovers) in beforeEach() instead of afterEach(). Why?

If the test fails in the middle, teardown might break (we don't have that created data to cleanup), or not be needed at all. So it is better to have initial Cleanup (setup) rather than doing it post-test.
What we’re doing during cleanups is actually one of the most important functionality of our application. If there’s a bug in the cleanup process itself, it’s better to catch it early during Setup and halt the test run. That way, we can investigate the issue before running the actual tests—no point in continuing when the app might already be in a broken state.
You need a clean state before each test, regardless of previous test outcomes, since the next test may doesn't know what happened in previous tests. Leftover data might mess with the next tests, so we need to clean up in Setup even if we are doing that in Teardown. This often makes teardown redundant.
Faster feedback and cleaner report/logs. You don’t really need to populate a lot of logs after the actual test phase. We want a clean report to debug when something is failed. So any preparation would be better to be in Setup instead of Teardown.

That’s why we have Arrange / Act / Assert, meaning we should handle environment preparation in Arrange.

However, while it's best to rely on setup to create clean state, teardown is still essential and needed in specific situations. Including:

Logging screenshots or any debug artifacts when the test is failed
Resetting feature flags or general state of the system, environment or application. (e.q. theme changes, a banner activated in UI, etc)
Cleanup Data you put in DATABASE (that can be mess with the next test) or Files (e.g. PDF, Log) you have created during the test.
Releasing shared cloud resources. For example, you are using an inhouse mobile device farm and you booked the only galaxys25-15Huj device in the farm for that test to check an specific Galaxy-AI driven functionality of your app.

Now let’s change our test suite and consider these improvements:

describe('CRUD Tests for /project', () => {
    let project;

    beforeEach('Delete the project after each test', () => {
         cy.request({
            method: 'DELETE',
            url: '/projects',
            failOnStatusCode: false,
            }).then((res) => {
                if (res.status !== 200 && res.status !== 404) {
                    throw new Error(`Unexpected DELETE status: ${res.status}`);
            }
});

    })

    context('CREATE and READ', () => {
        it('Should CREATE and READ a project', () => {
            // CREATE a Project
            cy.request('POST', '/project', { name: 'My Awesome Project' })
                .then((res) => {
                    project = res.body;

                    expect(res.status).to.eq(201)
                }).then(() => {
                    // READ the Project: we verify READ operation here by combining two tests. 
                    cy.request('GET', `/project/${project.id}`).its('body.name')
                        .should('include', 'Awesome');
                })
        });
    })

    context('UPDATE and DELETE', () => {
        beforeEach('Create a project before each test', () => {
            // Arrange
            cy.request('POST', `/project/${project.id}`, { name: 'My Awesome Project' })
                .then((res) => {
                    project = res.body;
                });
        })

        it('Should update a project', () => {
            // Act and Assert
            cy.request('PUT', `/project/${project.id}`, { name: 'Updated Project' })
                .then((res) => {
                    expect(res.status).to.eq(201)
                });
            cy.request('GET', `/project/${project.id}`).its('body.name')
                .should('eq', 'Updated Project');
        });

        it('Should delete a project', () => {
            // Act and Assert
            cy.request('DELETE', `/project/${project.id}`)
                .then((res) => {
                    expect(res.status).to.eq(200)
                });
            cy.request({
                method: 'GET',
                url: `/project/${project.id}`,
                failOnStatusCode: false
            }).its('status').should('eq', 404);
        });

    })

});

Did you notice the changes?

We have now two context()s inside the describe(). One for tests that don’t need a project setup, another for tests that do. We're grouping tests based on their setup requirements (condition).

Then we moved that initial beforeEach() hook (which is for creating project as a setup stage) inside the second context().
Instead of deleting the created project after tests in afterEach() as a teardown, we now delete all the projects in the database in the describe-scoped beforeEach() hook, which runs before the context's beforeEach() hook. (Sounds confusing? Don’t worry, I will explain it in a short ))
We’ve combined READ and CREATE tests! You might say: “Hey! Each test should have a single responsibility and test one thing!”, You are absolutely right, however, we already use the READ API to verify CREATE and UPDATE operations. So why have a separate READ test when we'd just recreate the same steps?

Considering that we need to CREATE a project again and then READ it; Doesn’t it look like exactly the same as the first test which is CREATE and READ for assertion? That’s why we usually end up with not having a separate test for READ. As a rule of thumb in automation, if you end up with two tests that their ARRANGEs, ACTs and ASSERTs look the same, there is a high chance that you are repeating the same test with just another name!

Let's look at how the hooks execute in sequence when we run the "Should update a project" test:

beforeEach() in describe block
beforeEach() in second context() block
it('Should update a project')

Authentication?

Until now, we've simplified our examples by omitting headers. However, each API call typically requires an authentication token (like JWT Bearer). Let's say we have a programmatic login method that handles authentication and retrieves the auth token. In real project, We usually add these commands inside cy.session() and keep them as custom commands (cypress/support/commands.js).

We want to execute this method once before our tests begin. This means we need something that:

Runs one time before anything
Has a scope of the entire describe()

What fits these requirements? Exactly, a before() hook inside the describe() hook. Let's implement it:

describe('CRUD Tests for /project', () => {
    let project;
    let token

    before('Login programmatically and fetch the token', () => {
        cy.request('POST', '/token', { username: Cypress.env('USERNAME'), password: Cypress.env('PASSWORD') })
            .then((res) => {
                expect(res.status).to.eq(201)
                token = res.body.authToken;
            })
    })

    beforeEach('Delete the project after each test', () => {
        cy.request({
            method: 'DELETE',
            url: '/projects',
            headers: { Authorization: token },
            failOnStatusCode: false,
            }).then((res) => {
                if (res.status !== 200 && res.status !== 404) {
                    throw new Error(`Unexpected DELETE status: ${res.status}`);
            }
        })
    })

    context('CREATE and READ', () => {
        it('Should CREATE and READ a project', () => {
            // CREATE a Project
            cy.request('POST', '/project', {'Authorization': token}, { name: 'ABC Project' })
                // ...
        });
    })

    context('UPDATE and DELETE', () => {
        beforeEach('Create a project before each test', () => {
            cy.request('POST', '/project', {'Authorization': token}, { name: 'ABC Project' })
                .then((res) => {
                    project = res.body;
                });
        })

        it('Should update a project', () => {
            // Act and Assert
            cy.request('PUT', `/project/${project.id}`, {'Authorization': token}, { name: 'Updated Project' })
                // ...
            cy.request('GET', `/project/${project.id}`).its('body.name')
                .should('eq', 'Updated Project');
        });

        it('Should delete a project', () => {
            // Act and Assert
            cy.request('DELETE', `/project/${project.id}`, {'Authorization': token})
                // ...
        });
    })
});

We defined a global variable called token
We defined a before() hook inside our describe() block that runs once before all tests.
Inside this hook, we get the authentication token from the response and assign it to our token variable > token = res.body.authToken
We then use this token in all subsequent request calls by adding it to the headers: > {'Authorization': token}

Is there any other way instead of using different contexts?

Sure there are! For example we can filter tests based on other attributes like test titles. While this approach makes tests organization appear simpler, it's not recommended since it creates a dependency on elements likely to change. Additionally, future users may not maintain this practice.

describe('CRUD Tests for /project', () => {
    let project;
    let token

    before('Login programmatically and fet the token', () => {
        //...
    })

    beforeEach('Delete the project after each test', () => {
        // STEP 1: delete projects
        cy.request('DELETE', `/projects`, {'Authorization': token})

        // STEP 2: Create a project only if the test is not a CREATE operation
        if (Cypress.currentTest.title.includes('|CREATE|')) return; 
        cy.request('POST', '/project', {'Authorization': token}, { name: 'ABC Project' })

    })

    it('Should |CREATE| and |READ| a project', () => {
        //...
    });

    it('Should |UPDATE| a project', () => {
        //...
    });

    it('Should |DELETE| a project', () => {
        //...
    });
});

We removed the context() blocks and moved the project creation setup into our single beforeEach() hook. This hook now has two operations: 1. deleting any existing projects (which runs for every test), and 2. adding a new project for each test IF it's not testing project creation itself. How can we implement this condition?

Notice that line > if (Cypress.currentTest.title.includes('|CREATE|')) return; , it says if the test title contains |CREATE|, stop at this point and return! otherwise continue and create a new project.

2. Use dynamic variables

2.1 Varibles inside the tests:

Did you notice those dynamic variables project and token we have defined in the beginning of the describe block?: As I mentioned, file-scoped or framework-scoped variables help keep tests independent and dynamic. Here we have this project variable that stores project object we create for each test. Take a look at the entire file to see how we use it for various operations.

2.2 Variables available globally

Sometimes we need something to be available in entire framework for all tests, that variable can be defined in cypress config file and is accessible using Cypress.config('VARIABLE'), if it is something needed to be changed based on environment, we can use env variables as well and access using Cypress.env('VARIABLE')

2.3 Run something before everything else!

Don't forget that we have global hook (cypress/support/e2e.js) that runs when cypress initializes before any tests start running. Think of it like a pre-test stage in CI, but internal to Cypress. It’s a great place to set up anything environment-related or handle global authentication if all tests use the same credentials.

This is also a good place to add an uncought:exception handler like the snippet below o prevent Cypress from failing when an unhandled exception occurs in the application:

Cypress.on('uncaught:exception', (e, runnable) => {
    console.log(e)
    // ignore the error
    return false
})

We can also use before() or beforeEach() in this file. These hooks will run globally across all tests, just like they do within individual test files, but with a broader scope that applies to the entire test framework.

3. Use random data (string/UUIDs, etc. )

When it comes to isolation, unique test data is crucial. We often have some hardcoded constants test data like fixtures or mock objects that can be used without any concern. For example assuming our project has a property called customersMetrics which is a complicated JSON object that we know and agreed can remain constant across all calls. We simply store this in a file named customer-metric-data.json in our fixture folder and use it in our test.

But what about projectTitle?

Consider when you're developing UI tests with approaches from this article (the same Setup stages with API but Test stages with UI). You should locate the project by its title using the locator [data-cy='project-title-GIVENNAME'], where GIVENNAME, is something that we should put in the body of the project create post call (thanks to our frontend guy for making this dynamic attribute assigning).

Can we use the same name each time? As long as we operate on One project, we are good. But let's say we want to write the "pagination" or "table filter" tests that require 10 or 20 projects created in test Setup. Then it becomes problematic.

Or Imagine a test fails and you need to debug by checking the logs to find that specific project. With 10 identical project names, how do you know which one failed?!

Or even more complicated, think about that situation I mentioned at the beginning of this article > You, your colleague and those 3 CI machines testing at the same time ….

To solve this issue, we should generate random values for variables and test data. Many libraries like fakerjs or uuid can help with this., or you can create your own random data following some specific patterns. Here’s some examples:

Random String:

const randomString = Math.random().toString(36).substring(2, 10); // oyxbwrhk
const randomEmail= `cypress-test-${randomString}@email.com` // cypress-test-oyxbwrhk@email.com

Random valid UUID:

import { v4 as uuidv4 } from 'uuid';

const envId= uuidv4() // 23f73210-68a0-4fbb-b261-8c0301a58dbe

Dynamic locator variable (as mentioned above)

support/utils.js

// Utility method to generate a random name for entities 
const generateRandomString = (postfix) => {
    const randomString = Math.random().toString(36).substring(2, 10);
    return {
        generatedString: `Cypress Test ${postfix} ${randomString}`,
        locatorValue: `${postfix.toLowerCase()}${randomString}`.replace(/\s/g, '-')
    };
}

page-objects/project-page.js

class ProjectPageObjects {
  //...
  static projectTitle = (str) => `[data-cy='project-title-${str}']`
}

export default ProjectPageObjects;

e2e/api/project-crud.cy.js

import ProjectPageObjects from '../../support/page-objects/project-page.js'
import { generateRandomString } from '../../support/utils.js';
// ...
it('Should |UPDATE| the Project from UI', () => {
    // ...
    const randomStringForCreate = generateRandomString('Project Updated Name')
    const randomProjectNewName = randomStringForCreate.generatedString
    const createdProjectLocatorValue = randomStringForCreate.locatorValue

    cy.get(ProjectPageObjects.titleEditInput).clear().type(randomProjectNewName)
    cy.get(ProjectPageObjects.editSubmitButton).click()
    // ...
    cy.get(ProjectPageObjects.titleName(createdProjectLocatorValue)).should('be.visible').should('have.text', randomProjectNewName)
        })

Cypress Test Isolation option:

There are a bunch of things that often get left behind by previous tests, like cookies, local storage, page context, etc.; not just the data or changes we create by the test. To ensure a truly clean state and full test independence, we need to handle those as well. That’s why Cypress, by default, resets the test environment between tests to make sure each one runs in complete isolation, free from any leftover state. This behavior can be turned off if needed, but it's generally recommended to keep it on. Check out the official documentation and also this blog post for more details.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 11 - Use Appium Inspector to Create Gestures

Moe Monfared — Sun, 27 Apr 2025 23:18:26 +0000

Overview
What is Appium Inspector?
Creating Pointers
Adding Actions
Saving the Gesture
Running the Gesture on the App

Overview

This is the eleventh part (last one) of the complete Gestures guide in the Appium series.

Did you know that there's a very interesting feature in the Appium Inspector designed to create gestures for us? It's like drawing gestures on your app screen!

What is Appium Inspector?

I'm pretty sure that the reader is familiar with this tool since it's used to locate elements, and we use it from day one in mobile automation. However, for those who don't know, it's a desktop application (available on Windows, Mac, and Linux) used to locate elements of the application and write locators.

Link to the project: https://github.com/appium/appium-inspector

Documentation: https://appium.github.io/appium-inspector/latest/

You can familiarize yourself with this app in its GitHub repo and official documentation, especially the Gestures tab which we are going to use here.

In this demo, we're going to perform a Zoom In (Pinch) on Google Maps, similar to what we did in Part 8.

Creating Pointers

In Appium Inspector, you can create as many pointers as you want to represent the fingers. We need two fingers to perform a Zoom, one moving to the left and one to the right.

Adding Actions

As mentioned in Part 8, we should perform a drag for each finger in the opposite direction (Move > Pointer Down > Move > Pointer Up).

For each action, we add an action card and then we set the Action Type. Next, we should choose the points on the map. It can be a percentage of the screen bonding area (%) or simply coordinates in pixels (px). You can see there is a button on the app to switch between these units. You can also type them manually (when you move the mouse, on the left top of the screen, the current hover coordinates are shown). Additionally, we can set Duration in milliseconds and left/right button if applicable, which you can see in the action card.

Now let's finish the actions for our left finger.

The same for the second finger (right):

At the end, you'll see a timeline for each finger, which shows the steps of the gestures. Pay attention to the arrow direction (up for Pointer Up, down for Pointer Down, and right for Move). Additionally, by hovering the mouse over each step, you will see the details related to that step.

To fine-tune the gesture, you may manually change the values of the coordinates. We can set all y coordinates equal to each other (as explained in Part 8) and make the drag distance of each finger equal but in opposite directions. For example, +400px and -400px.

In my case, I changed them to the following:

Finger 1 > (500, 1300) to (300, 1300)
Finger 2 > (800, 1300) to (1100, 1300)

With a duration of 50 milliseconds for each move action.

Saving the Gesture

By clicking on Save As this gesture will be saved in the list, and you can rename, delete, or add a description later.

Running the Gesture on the App

You can run the Gesture by clicking the Play button located in the Builder panel or Saved list. Keep the emulator visible to see the gesture.

Thank you for taking the time to read the final part of the "Gestures in Appium" series! ❤️ 🙏

If you enjoyed this and the series, please leave your reactions, comments, and questions. I’d love to hear your feedback!

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 10- Perform gestures in Mobile Web Browsers

Moe Monfared — Sun, 27 Apr 2025 23:08:17 +0000

Overview
Set Chrome Driver's binary path
Drag and Drop on Chrome Mobile Browser

Overview

This is the tenth part of the complete Gestures guide in the Appium series. So far, we've covered all possible gestures in native mobile applications. But what if we want to perform gestures in mobile browsers like Chrome Mobile? This means doing actions on websites opened by mobile browsers. Or what if that page is in a WebView context (in a Hybrid App)?

Actually, it's the same as using Selenium, since we are automating a web page. The only difference is to use the AppiumBy class instead of the By class. Also, we need to pass the driver binary.

Set Chrome Driver's binary path

We know it's required to specify the browser's driver binary in Selenium. But after version 4.6, they introduced SeleniumManager. It combines all the older driver manager libraries and can download and set up the right driver automatically if we don't define where it is located.
For mobile web browsers in Appium, managing the driver file is also mandatory. We can either tell Appium where to find the driver binary file or let it download and automatically set the right version it needs for the browser. So, we have three ways to do this:

1.Let Appium download and handle the driver's binary automatically by passing a flag to the Appium server. To do this we should run the following command to start the server instead of a single appium command

appium server --allow-insecure chromedriver_autodownload

2.Manually download the driver binary from the official website and copy it to the following path on your system. (The win folder at the end indicates it's for Windows since I'm on Windows now; for Mac and Linux, the last directory will be mac and linux ):

/USER_HOME/.appium/node_modules/appium-uiautomator2-driver/node_modules/appium-chromedriver/chromedriver/win

Note that if you are using Chrome version under 115, you should download the driver binary from here.

3.Add "chromedriverExecutable: <DRIVER_PATH>" to desired caps appium options

desired_caps = {
    "platformName": "Android",
    "browserName": "Chrome",
    "appium:options": {
        "automationName": "UiAutomator2",
        "chromedriverExecutable": "C:/chromedriver.exe"  # This line
    }
}

Drag and Drop on Chrome Mobile Browser

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from selenium.webdriver.common.action_chains import ActionChains

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.chrome)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.get("https://selenium08.blogspot.com/2020/01/drag-drop.html")

el1 = driver.find_element(AppiumBy.CSS_SELECTOR, '#draggable')
el2 = driver.find_element(AppiumBy.CSS_SELECTOR, '#droppable')

actions = ActionChains(driver)
actions.w3c_actions.pointer_action.click_and_hold(el1)
actions.w3c_actions.pointer_action.pause(1)
actions.w3c_actions.pointer_action.move_to(el2)
actions.w3c_actions.pointer_action.release()
actions.perform()

First, we create an instance of the ActionChains class:

actions = ActionChains(driver)

Next, we define our gesture steps. We choose w3c_actions to build our W3C-compatible gesture, followed by the pointer_action property since our input is a Pointer (left/right click of mouse, or touch), not a Mouse Wheel or Keyboard. I explained this inputs in detail in Part 8. Ending with actions for each step.

actions.w3c_actions.pointer_action.click_and_hold(el1)
actions.w3c_actions.pointer_action.pause(1)
actions.w3c_actions.pointer_action.move_to(el2)
actions.w3c_actions.pointer_action.release()

And finally, we perform all defined actions to be executed:

actions.perform()

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article (which is the last one of this series), we will explore an interesting feature of Appium Inspector that is used to create mobile gestures!

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 9- Plugin

Moe Monfared — Sun, 27 Apr 2025 23:06:31 +0000

Overview
Scroll Element Into View (Search) using Gestures Plugin
Drag and Drop using Gestures Plugin

Overview

This is the ninth part of the complete Gestures guide in the Appium series.

There is a plugin called appium-gestures-plugin from the AppiumTestDistribution team, who are famous for their useful plugins. So, I thought it is worth talking a bit about it here in this series.

The repository itself is the best place to follow the project, but this post is a sample in Python which was not included in their docs. In short, this plugin supports the following gestures as of the time of writing this blog post:

Swipe Left, right, up and down
scrollElementIntoView
Drag and Drop
Double Tap
Long Press

To install it, run the following command in your terminal:

appium plugin install --source=npm appium-gestures-plugin

Then run the appium server including the --use-plugins=gestures option, which indicates that we want to run the server using an installed plugin named gestures:

appium --use-plugins=gestures

To use this plugin, we should run commands like we did with the W3C Mobile Gestures Commands so far. The following are the commands we can use:

Swipe Left, right, up and down > gesture: swipe
scrollElementIntoView > gesture: scrollElementIntoView
Drag and Drop > gesture: dragAndDrop
Double Tap > gesture: doubleTap
Long Press > gesture: longPress

Now let's do some demos:

Scroll Element Into View (Search) using Gestures Plugin

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
list_view = driver.find_element(by=AppiumBy.ID, value='android:id/list')
driver.execute_script('gesture: scrollElementIntoView',
                      {'scrollableView': list_view.id, 'strategy': 'accessibility id', 'selector': 'Picker',
                       'percentage': 50, 'direction': 'up', 'maxCount': 3})

Let's take a look at the arguments:

scrollableView: This is the same scroll bounding area we had so far. Note that you should pass the session's id property of the element which is accessible via elementObject.id
strategy and locator : These are a pair used to find the element we want to scroll into view (want to search for it)
percentage: This indicates how much of the scroll bounding area we want to use to perform the gesture.
direction: This can be up , down , left and right
maxCount: This specifies how many times the driver is allowed to perform the gesture to find the element.

Drag and Drop using Gestures Plugin

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Drag and Drop').click()

el1 = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/drag_dot_1')
el2 = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/drag_dot_2')

driver.execute_script('gesture: dragAndDrop', {
    'sourceId': el1.id,
    'destinationId': el2.id,
})

The gesture: dragAndDrop the command simply accepts sourceId and destinationId which are the session's id properties of the starting (draggable) and ending (droppable) elements.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will see how we can perform gestures in Mobile Web Browsers.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 8 - Zoom (Pinch)

Moe Monfared — Sun, 27 Apr 2025 23:05:45 +0000

Overview
- How to perform Zoom In/out (Pinch Open/Close) in Appium?
Zoom (Pinch) In/Out using W3C Mobile Gestures Commands
Zoom (Pinch) In/Out using Actions API - W3C

Overview

This is the eighth part of the complete Gestures guide in the Appium series. In this guide, we will learn how to perform Zoom In/Out (Pinch) action.

We do zooming to see the details, mostly on photos but sometimes on other elements like maps.

During my career, I've rarely used this gesture, but it might be needed for some cases like automating maps/polygons. By the way, in order to finish the testing task you might need Visual Testing as well since the details on elements like maps or photos are not intractable.

How to perform Zoom In/out (Pinch Open/Close) in Appium?

Well. How do you do it manually? You put two fingers on the screen and then drag them in opposite directions. Right? Ok, In which direction? Up/down or right/left? The answer is clear, it isn't important. If the directions are exactly opposite it will perform zoom.

So we need 4 points on the screen:

Finger 1 starting point
Finger 1 ending point
Finger 2 starting point
Finger 2 ending point

We can move our fingers in the same horizontal line (same y) right? So, this means the x coordinates only should be defined and all y coordinates can be the same. Now we just need 4 points as x coordinates.

Now let's implement it.

Zoom (Pinch) In/Out using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from time import sleep

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.maps)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.implicitly_wait(10)
driver.find_element(by=AppiumBy.XPATH, value="//*[@text='SKIP']").click()
sleep(5)  # For demo purpose / wait to load maps

# Zoom In
driver.execute_script('mobile: pinchOpenGesture', {
    'left': 200,
    'top': 800,
    'width': 1000,
    'height': 1000,
    'percent': 0.5,
})

sleep(0.5)  # For demo purpose

# Zoom Out
driver.execute_script('mobile: pinchCloseGesture', {
    'left': 200,
    'top': 800,
    'width': 1000,
    'height': 1000,
    'percent': 1,
})

As you can see, there are two commands in W3C Mobile Actions to achieve this. mobile: pinchOpenGesture and mobile: pinchCloseGesture. Like most of the other commands we've covered so far, you should either pass the element to be pinched or define the pinch bounding area using a combination of left, top, width and height arguments. If you don't have any idea what the pinch/scroll/swipe bounding area is, please refer to Part 4 where I explained it in detail.

Zoom (Pinch) In/Out using Actions API - W3C

So far we have utilized previously created gesture methods in ActionHelpers . However, as mentioned in the previous part, it doesn't include any gesture for pinching yet. Actually, ActionHelper class is just a (good and standard) sample of how we can create gestures using W3C Actions API. As noted in Part 1, we are not limited, we can create any gestures we can imagine using the W3C Actions API.

With this understanding, I'm going to implement our Zoom In/out (Pinch Open/Close) methods using W3C Actions API. Let's first take a look at the final code, and I will provide a detailed explanation afterward.

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from time import sleep

# To create our own W3C compatible gesture 
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.actions.mouse_button import MouseButton

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.maps)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.implicitly_wait(10)
driver.find_element(by=AppiumBy.XPATH, value="//*[@text='SKIP']").click()
sleep(5)  # For demo purpose / wait to load maps

# Get the size of the window
window_size = driver.get_window_size()

# Calculate center point on the screen
center_x = window_size['width']/2
center_y = window_size['height']/2
print(f'Center: {center_x}px, {center_y}px') # To check/demo in console

# Create an instance from ActionChains class
actions = ActionChains(driver)

# Free up any previously added input device (make sure to put in real projects)
actions.w3c_actions.devices = []

# Define two touch pointers (fingers)
finger1 = actions.w3c_actions.add_pointer_input('touch', 'finger1')
finger2 = actions.w3c_actions.add_pointer_input('touch', 'finger2')

# Zoom In
finger1.create_pointer_move(x=center_x-100, y=center_y)
finger1.create_pointer_down(button=MouseButton.LEFT)
finger1.create_pause(0.5)
finger1.create_pointer_move(x=center_x-500, y=center_y, duration=50)
finger1.create_pointer_up(button=MouseButton.LEFT)

finger2.create_pointer_move(x=center_x+100, y=center_y)
finger2.create_pointer_down(button=MouseButton.LEFT)
finger2.create_pause(0.5)
finger2.create_pointer_move(x=center_x+500, y=center_y, duration=50)
finger2.create_pointer_up(button=MouseButton.LEFT)

actions.perform()
sleep(0.5)  # For demo purpose

# Zoom Out
finger1.create_pointer_move(x=center_x-500, y=center_y)
finger1.create_pointer_down(button=MouseButton.LEFT)
finger1.create_pause(0.5)
finger1.create_pointer_move(x=center_x-100, y=center_y, duration=50)
finger1.create_pointer_up(button=MouseButton.LEFT)

finger2.create_pointer_move(x=center_x+500, y=center_y)
finger2.create_pointer_down(button=MouseButton.LEFT)
finger2.create_pause(0.5)
finger2.create_pointer_move(x=center_x+100, y=center_y, duration=50)
finger2.create_pointer_up(button=MouseButton.LEFT)

actions.perform()

First I calculated the center point on the screen by dividing the window height and width by 2:

# Get the size of the window
window_size = driver.get_window_size()

# Calculate center point on the screen
center_x = window_size['width']/2
center_y = window_size['height']/2

Next, I created an instance from the ActionChains class and cleared any previously added input device. You should do this in real projects since you might use the same ActionChains instance across your tests.

# Create an instance from ActionChains class
actions = ActionChains(driver)

# Free up any previously added input device (make sure to put in real projects)
actions.w3c_actions.devices = []

Now we need two fingers! In the following code, actions is our instance of ActionChains class, and w3c_actions means we are going to use W3C Actions API. But what is add_pointer_input ?

As explained in W3C Actions API Standard and Part 1 of this series, we have 3 types of input: (key, pointer, wheel). We should use pointer since it is neither a Keyboard nor a Mouse Wheel. Our input is going to be a pointer. Now, for pointers, we also have three types: (touch, pen, mouse). So we use touch input since we are going to perform actions by touching the screen, not by a Pen or a Mouse connected.

# Define two touch pointers (fingers)
finger1 = actions.w3c_actions.add_pointer_input('touch', 'finger1')
finger2 = actions.w3c_actions.add_pointer_input('touch', 'finger2')

Ok, now we actually need to perform a drag and drop with each finger. One to the left and one to the right. As mentioned in the previous part, drag and drop means (move to A > hold > move to B> release).

However, we should do them together somehow. We can't perform one finger's gesture and then the next one after it. They should be performed simultaneously. That's why we have the perform() method in ActionChains class. We define all our actions and then perform them all together.

So, for zooming in, we will have:

# Zoom In
finger1.create_pointer_move(x=center_x-100, y=center_y)
finger1.create_pointer_down(button=MouseButton.LEFT)
finger1.create_pause(0.5)
finger1.create_pointer_move(x=center_x-500, y=center_y, duration=50)
finger1.create_pointer_up(button=MouseButton.LEFT)

finger2.create_pointer_move(x=center_x+100, y=center_y)
finger2.create_pointer_down(button=MouseButton.LEFT)
finger2.create_pause(0.5)
finger2.create_pointer_move(x=center_x+500, y=center_y, duration=50)
finger2.create_pointer_up(button=MouseButton.LEFT)

actions.perform()

and for zooming out:

# Zoom Out
finger1.create_pointer_move(x=center_x-500, y=center_y)
finger1.create_pointer_down(button=MouseButton.LEFT)
finger1.create_pause(0.5)
finger1.create_pointer_move(x=center_x-100, y=center_y, duration=50)
finger1.create_pointer_up(button=MouseButton.LEFT)

finger2.create_pointer_move(x=center_x+500, y=center_y)
finger2.create_pointer_down(button=MouseButton.LEFT)
finger2.create_pause(0.5)
finger2.create_pointer_move(x=center_x+100, y=center_y, duration=50)
finger2.create_pointer_up(button=MouseButton.LEFT)

actions.perform()

What are ("x-100", "x+100", "x-500" and "x+500")?

In this figure, (x, y) represents our center point (center_x, center_y).

Finger 1 starting point : (x-100, y)
Finger 1 ending point : (x-500, y)
Finger 2 starting point : (x+100, y)
Finger 2 ending point : (x+500, y)

So, we start from a distance of 100 pixels from the center to avoid collisions with our fingers. Then we move our left finger 400 pixels to the left (from x-100 to x-500) and move our right finger 400 pixels to the right (from x+100 to x+500). All this is done along the same horizontal line (y remains constant).

What is MouseButton.LEFT ?

The MouseButton class is a kind of enum that indicates the button of the input we want to perform the action with. For example, you might want to use the middle or right button of the mouse to perform an action. In touch input, since there is only a finger, we use the primary and default input button, which is 0 or MouseButton.LEFT.

class MouseButton:
    LEFT = 0
    MIDDLE = 1
    RIGHT = 2
    BACK = 3
    FORWARD = 4

Hey, I am confused. We are doing touch actions here. Why are you talking about the Mouse?

Well, as mentioned many times, Appium is built on top of the Selenium and uses the same TouchActions class to implement gestures, and that's the reason we utilize Selenium libraries in many cases.

To achieve Zoom out we do all the actions vice versa by simply swapping starting and ending points.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will talk about a Plugin available for performing gestures.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 7- Drag and Drop

Moe Monfared — Sun, 27 Apr 2025 23:03:15 +0000

Overview
What is Drag and Drop?
Drag and Drop using W3C Actions API
Drag and Drop using W3C Mobile Gestures Commands

Overview

This is the seventh part of the complete Gestures guide in the Appium series. In this guide, we will learn how to perform Drag and Drop action. It is one of the most important gestures in mobile automation, and mastering it is essential. Let's dive in!

What is Drag and Drop?

Well, the name defines itself. You pick something and drop it somewhere else, It consists of 4 actions:

Moving to point A (starting point)
Holding the finger to pick items
Dragging to point B (ending point)
Release the finger to drop

Drag and Drop using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.wdio)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.implicitly_wait(5)
driver.find_element(AppiumBy.ACCESSIBILITY_ID, 'Drag').click()
draggable_el = driver.find_element(AppiumBy.ACCESSIBILITY_ID, 'drag-c1')
droppable_el = driver.find_element(AppiumBy.ACCESSIBILITY_ID, 'drop-c1')

driver.drag_and_drop(draggable_el, droppable_el)

The first and straightforward way to perform the Drag and Drop gesture is to use driver.drag_and_drop(origin_el, destination_el) , which accepts the origin and destination elements. Like driver.swipe() or driver.scroll() , it is another method of ActionHelpers class, accessible through the driver instance. So far we have learned all 5 ActionHelpers' methods to perform gestures:

driver.tap()
driver.flick()
driver.swipe()
driver.scroll()
driver.drag_and_drop()

But this library is developing and we will see other methods in the future soon.

Drag and Drop using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.wdio)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.implicitly_wait(5)
driver.find_element(AppiumBy.ACCESSIBILITY_ID, 'Drag').click()
draggable_el = driver.find_element(AppiumBy.ACCESSIBILITY_ID, 'drag-c1')
droppable_el = driver.find_element(AppiumBy.ACCESSIBILITY_ID, 'drop-c1')

driver.execute_script('mobile: dragGesture', {
    'elementId': draggable_el,
    'endX': droppable_el.location['x'],
    'endY': droppable_el.location['y']
})

Let's first take a look at the supported arguments:

elementId: The id of the element to be dragged. If the element id is missing then both start coordinates must be provided. If both the element id and the start coordinates are provided then these coordinates are considered as offsets from the top left element corner.
startX: The x-start coordinate
startY: The y-start coordinate
endX: The x-end coordinate. Mandatory argument
endY: The y-end coordinate. Mandatory argument
speed: The speed at which to perform this gesture in pixels per second. The value must not be negative. The default value is 2500 * displayDensity

As can be seen, we should either pass elementId (element object) or the coordinates of it (startX, startY) for our starting point. Additionally, for ending point, it only accepts coordinates (endX, endY).

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will cover the Pinch (Zoom) gesture.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 6- Flick (Fling)

Moe Monfared — Sun, 27 Apr 2025 23:01:17 +0000

Overview
Flick (Fling) using W3C Actions API
Flick (Fling) using W3C Mobile Gestures Commands

Overview

This is the sixth part of the complete Gestures guide in the Appium series. In previous posts, we familiarized ourselves with Scrolling and Swiping and now we will learn how to perform the Flick gesture action. This action is also called Fling or, in some places, Flip.

If you are not familiar with the differences between these gestures, please refer to the previous post where I explained it in detail. In short, Flicking is a quick action where exact locations are not important (although we need them for Appoium), and it should be as fast as possible. It's akin to swiftly cutting fruits in the FruitNinja game!

Flick (Fling) using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
buttons_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')

# Flick Up
driver.flick(start_x=grid_el.location['x'], start_y=grid_el.location['y'], end_x=buttons_el.location['x'], end_y=buttons_el.location['y'])

# Flick Down
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')
picker_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Picker')

driver.flick(start_x=250, start_y=900, end_x=250, end_y=2300)

As we saw in the previous post for driver.swipe() we also have driver.flick() which accepts the coordinates of the starting (start_x, start_y) and ending points (end_x, end_y). It doesn't accept a duration since it should be the fastest possible flick action.

Flick (Fling) using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

# Flick Up - Using elementId
list_view = driver.find_element(by=AppiumBy.ID, value='android:id/list')
list_view_rect = list_view.rect

driver.execute_script('mobile: flingGesture', {
    'elementId': list_view,
    'direction': 'down',
    'percent': 1,
})

# Flick Down - Using coordinates
driver.execute_script('mobile: flingGesture', {
    'left': list_view_rect['x'],
    'top': list_view_rect['y'],
    'direction': 'up',
    'width': list_view_rect['width'],
    'height': list_view_rect['height'],
    'percent': 2,
})

To perform a Flick gesture using W3C mobile gestures commands, we should use mobile: flingGesture which, like other commands we covered so far, allows us to either define a flick bounding area using (left, top, width, and height values) or pass the element object (in this case, the element bounding area is considered as flicking area)

That's it. That simple.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will cover the Drag-and-Drop gesture.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 5 - Swipe (Vertical/Horizontal)

Moe Monfared — Sun, 27 Apr 2025 22:57:58 +0000

Overview
What is the difference between Scroll, Swipe, and Flick (Fling)?
- Scroll DOWN = Swipe UP?? I'm confused
Swipe Up and Down using W3C Actions API
Swipe Up and Down using W3C Mobile Gestures Commands
Swipe Left and Right using W3C Actions API
Swipe Left and Right using W3C Mobile Gestures Commands

Overview

This is the fifth part of the complete Gestures guide in the Appium series. In this guide, we will learn how to perform the Swipe action in all directions (up/down/right/left) which is something between Scroll and Flick (fling).

What is the difference between Scroll, Swipe, and Flick (Fling)?

Scroll: Moving contents of the page within a container (scroll bounding area) to 4 main directions (up, down, left, right). It is performed slowly and in a controlled manner. You release your finger at the end of the gesture, after you've moved the contents you're searching for into view. The same action we do in desktop browsers and OS using the scrollbar or mouse wheel. We scroll to view content that extends beyond the visible area of a screen.

Swipe: A quick but continuous movement of the finger across the screen in a particular direction (usually up/down/right/left as a scroll). It is very close to scrolling but is much faster than it, and you usually don't control the finger or follow contents as a scroll. It is commonly used for various interactions, such as navigating between screens or pages in an app, revealing additional options or actions (e.g., swiping to delete an item in iOS), or switching between different views or tabs.

Flick (Fling): It is a rapid movement of the finger across the screen as fast as possible. You don't care about contents and you don't control the finger movement. You release your finger while performing a Flick. For example, flicking up quickly and multiple times to reach the first message in a Telegram/WhatsApp thread or playing Fruit Ninja Game!

Scroll DOWN = Swipe UP?? I'm confused

I discussed it in the previous part but let me quickly explain again. Think about the scrollbar: When you scroll down, you are moving the scrollbar down to view the contents that are not visible, and the contents are moving up, right? But we are talking about a touchscreen, and there is no mouse and scrollbars. You should scroll using your finger, so to do the same thing (moving elements up), what should you do? Correct, move your finger UP on the screen, not down. That's the difference in direction between Scroll and Swipe/Flick actions. For example, in Appium, when we want to move to the bottom of the page, we pass direction=down for Scroll, but pass direction=up if we want to use Swipe or Flick gestures.

Now that we understand the differences, let's perform some Swipes!

Swipe Up and Down using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

buttons_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')

# Swipe Up
driver.swipe(start_x=grid_el.location['x'], start_y=grid_el.location['y'], end_x=buttons_el.location['x'], end_y=buttons_el.location['y'])

# Swipe Down
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')
picker_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Picker')
driver.swipe(start_x=grid_el.location['x'], start_y=grid_el.location['y'], end_x=picker_el.location['x'], end_y=picker_el.location['y'])

The first and straightforward way to perform Swipe is to use driver.swipe() . An ActionHelpers class' method which is accessible through the driver instance. It accepts 4 mandatory and 1 optional argument including:

start_x: x-coordinate at which to start
start_y: y-coordinate at which to start
end_x: x-coordinate at which to stop
end_y: y-coordinate at which to stop
duration: defines the swipe speed as the time taken to swipe from point A to point B, in milliseconds.

So in the given example, first I found the starting and ending elements. Two simple rows named buttons / grid

buttons_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')

And then using their location property which gives me the coordination pair of the elements, (explained in Part 1). I perform the Swipe Up gesture.

Then I performed Swipe Down.

Why you queried driver_find() again for swiping up? Couldn't you just swap the coordination? element.location actually queries the element again, While grid_el is still on the view (moved to the top) button_el is not causing the test to fail. Therefore I used grid_el as my starting point but found another element at the bottom of this view to perform the action.

I intentionally did it this way to demonstrate what happens behind the scenes with the location property, so you won't be confused in the future. Now that we understand the concept, instead of querying the elements again, we can store the location value in a variable initially and then use it later. This way, we won't need to call the location again.

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

# Get elements
buttons_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')

# Get coordinations
up_coords = {'x': buttons_el.location['x'], 'y': buttons_el.location['y']}
down_coords = {'x': grid_el.location['x'], 'y': grid_el.location['y']}

# Swipe Up
driver.swipe(start_x=down_coords['x'], start_y=down_coords['y'], end_x=up_coords['x'], end_y=up_coords['y'])

# Swipe Down
driver.swipe(start_x=up_coords['x'], start_y=up_coords['y'], end_x=down_coords['x'], end_y=down_coords['y'])

Swipe Up and Down using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

# Swipe Up - With Element
list_view = driver.find_element(by=AppiumBy.ID, value='android:id/list')
driver.execute_script('mobile: swipeGesture', {
    'elementId': list_view,
    'direction': 'up',
    'percent': 0.3,
    'speed': 5000
})

# Swipe Down - With Element
list_view = driver.find_element(by=AppiumBy.ID, value='android:id/list')
driver.execute_script('mobile: swipeGesture', {
    'elementId': list_view,
    'direction': 'down',
    'percent': 0.3,
    'speed': 3000
})

In W3C Mobile Gestures Commands, we have mobile: swipeGesture, which like most of the mentioned commands we covered so far, supports the following arguments (as mentioned in the documentation):

elementId: The id (object) of the element to be swiped. If the element id is missing then swipe bounding area must be provided. If both the element id and the swipe bounding area are provided then the area is effectively ignored.
left: The left coordinate of the swipe bounding area
top: The top coordinate of the swipe bounding area
width: The width of the swipe bounding area
height: The height of the swipe bounding area
direction: Swipe direction. Mandatory value. Acceptable values are: up, down, left and right (case insensitive)
percent: The size of the swipe as a percentage of the swipe area size. Valid values must be float numbers in range 0..1, where 1.0 is 100%. Mandatory value. speed: The speed at which to perform this gesture in pixels per second. The value must not be negative. The default value is 5000 * displayDensity

So we either should pass the element object (found by driver.find()) or define the swiping bounding area which I explained well in the previous part. Also, the percent which is the percentage of swiping as a float number (e.g. 0.2) is a mandatory value. There is no default.
Important Note: I should reiterate in this post as well that if you pass an elementId to the command, it will use the element's bounds to determine the swiping area. So in our example, I passed the parent class of these elements (list_view) to be able to scroll the entire list. If I were to use any item from the list here instead of their parent element, it would limit the swiping area to only one row (between two horizontal lines).

Swipe Left and Right using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

appium_server = "http://127.0.0.1:4723"
import desired_caps # Explained in Part 1

appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Gallery').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Photos').click()

# Swipe Left
image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')
driver.swipe(image_views[2].location['x'], image_views[2].location['y'], image_views[0].location['x'], image_views[0].location['y'])

# Swipe Right
image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')
driver.swipe(image_views[0].location['x'], image_views[0].location['y'], image_views[2].location['x'], image_views[2].location['y'])

In the above example, we have several images in a horizontal row. By the following command, we find all of them:

image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')

then we swipe from the 3rd one in the list (index 2) to the first one (index 0) by passing coordination of those elements.

driver.swipe(image_views[2].location['x'], image_views[2].location['y'], image_views[0].location['x'], image_views[0].location['y'])

and vice-versa for swiping to the right. Note that we should find again the current elements in the view.

image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')
driver.swipe(image_views[0].location['x'], image_views[0].location['y'], image_views[2].location['x'], image_views[2].location['y'])

Swipe Left and Right using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Gallery').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Photos').click()

# Swipe Left
galley = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/gallery')
driver.execute_script('mobile: swipeGesture', {
    'elementId': galley,
    'direction': 'left',
    'percent': 0.3,
    'speed': 5000
})
# Swipe Right
galley = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/gallery')
driver.execute_script('mobile: swipeGesture', {
    'elementId': galley,
    'direction': 'right',
    'percent': 0.3,
    'speed': 3000
})

the last thing I wanted to cover in this post is how to perform horizontal swiping using W3C mobile gestures commands. As you can see above, I set the percent to 0.3 in order to limit swiping to just a portion of the row. Additionally, I reduced the speed for right swiping to demonstrate its effect on the gesture.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will cover the Flick (Fling) gesture.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 4 - Scroll (Vertical/Horizontal/Search and Scroll Element IntoView)

Moe Monfared — Sun, 27 Apr 2025 22:55:32 +0000

Overview
Scroll Up and Down using W3C Actions API
Scroll Up and Down using W3C Mobile Gestures Commands
Scroll using TouchAction class [DEPRECATED]
Scroll Right and Left using W3C Actions API
Scroll Right and Left using W3C Mobile Gestures Commands
Android UiScrollable Class
Scroll Element Into View (Search for element) using Android UiScrollable Class
Scroll Element Into View (Search for element) using W3C Mobile Gestures Commands
Scroll to End | Scroll to Beginning

Overview

This is the fourth part of the complete Gestures guide in the Appium series. In this guide, we will learn how to perform Scroll action in all directions (up/down/right/left) and search for elements using scroll to bring them into view (Scroll Element Into View).

Scroll Up and Down using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from time import sleep

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

## Scroll Down
# Get origin element (Starting point)
buttons_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')

# Get destination element (Ending point)
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')

# Perform scroll using driverr.scroll()
driver.scroll(origin_el=grid_el, destination_el=buttons_el)

sleep(1)  # For demo purpose

## Scroll Up
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')
picker_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Picker')
driver.scroll(grid_el, picker_el)

To perform scrolling using W3C actions, we can utilize the scroll() method accessible through the driver instance (An ActionHelpers class' method). This method accepts starting and ending points as first and second arguments. Additionally, you can set the speed of the action (in milliseconds) as the third argument. This is optional and the default value is 600ms. scroll(origin_el, destination_el, duration)

Scroll Up and Down using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

# Scroll Down - with Element
list_view = driver.find_element(by=AppiumBy.ID, value='android:id/list')
driver.execute_script('mobile: scrollGesture', {
    'elementId': list_view,
    'direction': 'down',
    'percent': 2,
})

# Scroll Up - with Element
list_view = driver.find_element(by=AppiumBy.ID, value='android:id/list')
driver.execute_script('mobile: scrollGesture', {
    'elementId': list_view,
    'direction': 'up',
    'percent': 0.5,
    'speed': 1000
})

As mentioned before, performing actions with mobile gestures commands is easy, most-compatible, and cross-platform. The "mobile: scrollGesture" is the one we should pick to perform this gesture. Before talking about the code, let's take a look at the arguments this command accepts with the explanations from its documentation:

elementId: The id of the element to be scrolled. If the element id is missing then a scroll bounding area must be provided. If both the element id and the scroll bounding area are provided then this area is effectively ignored.
left: The left coordinate of the scroll bounding area
top: The top coordinate of the scroll bounding area
width: The width of the scroll bounding area
height: The height of the scroll bounding area
direction: Scrolling direction. Mandatory value. Acceptable values are: up, down, left and right (case insensitive)
percent: The size of the scroll as a percentage of the scrolling area size. Valid values must be float numbers greater than zero, where 1.0 is 100%. Mandatory value.
speed: The speed at which to perform this gesture in pixels per second. The value must not be negative. The default value is "5000 * displayDensity"

What is Scroll Bouding Area? This term refers to the allowed area where we can scroll on a scrollable element. When we attempt to scroll on an element that is not scrollable, the gesture will either not work or will be disrupted. For example, when scrolling down (moving finger up), if we reach the status bar area, we cannot continue scrolling. Alternatively, if we start scrolling up (moving finger down) from the notification bar, it will open the notification center or quick settings button instead of scrolling. Therefore, the driver should know about this allowed area so that it doesn't move out of the scrollable area.

Now that we understand what the scrollable area is, We should know that there are two ways to define the scrollable area for mobile gesture commands like Scroll, Swipe, and Zoom (Pinch):

Pass the element object (elementId), and in this case, the bounding area would be the element bounds (as explained in Part 1). Set the top, left, width and height values for it (in pixels), which is shown in the following figure:

Important Note: As mentioned just now, if you pass an elementId to the command, it will use the element's bounds to determine the scrolling area. So in our example, I passed the parent class of these elements (list_view) to be able to scroll the entire list. If I were to use any item from the list here instead of their parent element, it would limit the scrolling area to only one row (between two horizontal lines).

The direction and speed are clear. Let's talk about perecnt. It simply says how much of the scroll bounding area we want to scroll be performed. For example in the above figure, if I set 50% for this value, and down as direction, it will scroll from Grid to Drag and Drop items in this list.

Hey, stop! I'm confused, we move our finger up (from down to up), so why do you call it scrolling Down and not Up?

Let me make it even more confusing! For swipe we call vice versa (the one your brain accepts)! We say Swipe Up when swiping your finger from down to up and Swipe down when swiping from up to down! (We will see swipe gestures in the next posts). The same story with Left/Right scrolling/swiping.

But don't worry I will tell you know.
Scrolling: Think about the scrollbar direction. When you're scrolling down a page or a list on a touchscreen device, you move your finger upwards on the screen. This action causes the content on the screen to move downwards, revealing more content. Conversely, when you're scrolling up, you move your finger downwards on the screen. This action causes the content on the screen to move upwards.

Swiping: When you're swiping down, you use a quick flicking motion where you move your finger downwards on the screen. In Swiping up, you move your finger upwards on the screen. Like switching between your photos in the phone gallery or dismissing a notification from the notification bar. In iOS devices, it reveals options like delete or archive for elements in a list like contacts or chat threads.

Scrolling down: Moving your finger upwards on the screen to move content downwards.
Scrolling up: Moving your finger downwards on the screen to move content upwards.
Swiping down: Using a quick flicking motion to move your finger downwards on the screen.
Swiping up: Using a quick flicking motion to move your finger upwards on the screen.

Scroll using TouchAction class [DEPRECATED]

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.touch_action import TouchAction

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
actions = TouchAction(driver)

# Scroll Down (passing element coordination)
up_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')
down_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')
actions.press(el=down_el).move_to(x=up_el.location['x'], y=up_el.location['y']).release().perform()

# Scroll Up (passing element object)
grid_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')
picker_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Picker')
actions.press(el=grid_el).move_to(el=picker_el).release().perform()

In the TouchAction class, we can achieve scrolling by chainingpress().move_to().release().perform(). I think it is now crystal clear to you what we have done here. You can pass either element object or coordination for each action. Now I want to do something more interesting here:

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.touch_action import TouchAction

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
actions = TouchAction(driver)

# Get origin/destination elements
up_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Buttons')
down_el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Grid')

# Get these elements' coordination
up_el_coord = up_el.location
down_el_coord = down_el.location

# Get window size (Explained in Part 1)
window_size = driver.get_window_size()

# Calcualte center of the elements (Explained in Part 1)
down_el_x = window_size['width'] / 2 + down_el_coord['x']
up_el_x = window_size['width'] / 2 + up_el_coord['x']

# Perform Scroll using coordination
actions.press(x=down_el_x, y=down_el_coord['y']).move_to(x=up_el_x, y=up_el_coord['y']).release().perform()

We calculated the center of the elements and passed these values to our gesture sequence (from down_el_x to up_el_x) and the y is the same because we are performing vertical scroll.

Scroll Right and Left using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Gallery').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Photos').click()

# Scroll Right
image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')
driver.scroll(image_views[2], image_views[0], duration=400)

# Scroll Left
image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')
driver.scroll(image_views[0], image_views[2])

To perform a W3C-supported horizontal scroll (driver.scroll()) in the above screen, first, we find all image placeholders using driver.find_elements():

image_views = driver.find_elements(AppiumBy.CLASS_NAME, value='android.widget.ImageView')

then for performing Scroll Right, we should move our finger from right to left, so we choose the 3rd image (index 2 of the image_views list) as the origin and the first image (index 0) as the destination. Vice versa for Scroll Left.

Scroll Right and Left using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from time import sleep

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Gallery').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Photos').click()

# Scroll Right - with Bounds
driver.execute_script('mobile: scrollGesture', {
    'left': 500, 'top': 500, 'width': 500, 'height': 0,
    'direction': 'right',
    'percent': 1.0
})

sleep(1)  # For demo purpose

# Scroll Left - with Bounds
driver.execute_script('mobile: scrollGesture', {
    'left': 500, 'top': 500, 'width': 500, 'height': 0,
    'direction': 'left',
    'percent': 1.0
})

To set the scrollable area for my emulator screen, I set a bounding area starting from point (500,500) on the screen (a point on the images). The width of the area was set to 500px, while the height was set to 0 since we are going to perform a horizontal scroll and it is a good practice. To scroll through the entire scrolling bounding area, I set the percent value to 1.0, indicating a 100% scroll.

Android UiScrollable Class

Android developers are familiar with the UiSelector() and UiScrollable() classes in Android SDK. These are parts of the Android support-library and are used to locate elements and do gestures on them in Android testing. Following is an example of how it is used (Java language).

UiSelector element = new UiSelector().text("Accessibility");
element.click()

**Note for Android developers: As of now (March 2024), the support-library is recently **deprecated* and these classes are now maintained in AndroidX project which is an important component of Jetpack for testing. ( import androidx.test.uiautomator.UiSelector as an example for import)
Documentation: https://developer.android.com/reference/kotlin/androidx/test/uiautomator/package-summary*

Appium supports UiAutomator API with the help of ANDROID_UIAUTOMATOR selector. It is one of the AppiumBy strategies.

To locate an element using this selector we pass AppiumBy.ANDROID_UIAUTOMATOR as the by argument and the Java expression in string format for the value. e.g:

el = driver.find_element(by=AppiumBy.ANDROID_UIAUTOMATOR, value='new UiSelector().text("Accessibility")')

Yes, it should be like this. Even if you are using Java for Appium, you must pass the value as a string with the Java expression!

Scroll Element Into View (Search for element) using Android UiScrollable Class

Assuming you want to scroll in the page to find a specific element. Means that the driver bring that element into your view, so you can interact with it. The driver will search the entire scrollable area by scrolling in all possible directions and will find it for you regardless of where it is located. Let's see how we can achieve that using the library I just mentioned.

There is UiScrollable() class which can perform various gestures for us, such as scrollToEnd , scrollBackward, flingForward , etc. (You can refer to the documentation for a list of available methods)

For creating a new instance of UiScrollable Class and using its ScrollIntoView() method we would say:

new UiScrollable(UiSelector).scrollIntoView(UiSelector)

And we should pass another UiSelector object to the scrollIntoView method.

So the Java code would be:

// Create an instance from UiSelector and make it scrollable
UiSelector scrollableSelector = new UiSelector().scrollable(true).instance(0);

// Cretae an instance of UiSelector and use its text() locator method
UiObject scrollableElement = new UiSelector().text("Picker").instance(0);

// Now join them together to create an instance of UiScrollable class
new UiScrollable(scrollableSelector).scrollIntoView(scrollableElement);

So we ended up with something crazy like this to write in our test! :

java_value = 'new UiScrollable(new UiSelector().scrollable(true).instance(0)).scrollIntoView(new UiSelector().text("Picker").instance(0))'
el = driver.find_element(by=AppiumBy.ANDROID_UIAUTOMATOR, value=java_value)

scrollable(true) means that we want to create a scrollable UiSelector object and instance(0) will choose the first element found by that selector. Something like driver.find_elements(By, Value)[0]

And following is our final code:

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

# Using ANDROID_UIAUTOMATOR selector to find and element
el_to_find = driver.find_element(by=AppiumBy.ANDROID_UIAUTOMATOR, value='new UiScrollable(new UiSelector().scrollable(true).instance(0)).scrollIntoView(new UiSelector().text("Picker").instance(0))')
el_to_find.click()

Scroll Element Into View (Search for element) using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

#Scroll element into view
driver.execute_script('mobile: scroll', {'strategy': 'accessibility id', 'selector': 'Picker'})

There is a special gesture command in W3C Mobile Gestures which is "mobile: scroll". It is intended to perform exactly what we want, scrolling to bring the element into view. As shown in the example provided, I passed the combination of strategy and selector instead of element or coordination.

Scroll to End | Scroll to Beginning

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from time import sleep

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()

# ScrollToEnd
driver.find_element(by=AppiumBy.ANDROID_UIAUTOMATOR, value='new UiScrollable(new UiSelector().scrollable(true)).setAsVerticalList().scrollToEnd(5)')

sleep(1)  # For demo purpose

#Scroll To Beginning 
driver.find_element(by=AppiumBy.ANDROID_UIAUTOMATOR, value='new UiScrollable(new UiSelector().scrollable(true)).setAsVerticalList().scrollToBeginning(5)')

Here, we are utilizing the Android UiScrollable class again. Let's review the new methods:

setAsVerticalList() Sets the direction of swipes to be vertical when performing scroll actions.
setAsHorizontalList() Sets the direction of swipes to be horizontal when performing scroll actions.
scrollToEnd(maxSwipes) Scrolls to the end of a scrollable layout element
scrollToBeginning(maxSwipes) Scrolls to the beginning of a scrollable layout element

UiAutomator identifies the main scrollable element and scrolls to the beginning or end of the page. It is useful when you don't care about the contents and you just want to move the view into the most-top or most-down position.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will cover the Swipe gesture.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 3- Press and Hold (Long Press)

Moe Monfared — Sun, 27 Apr 2025 22:52:48 +0000

Overview
Press and Hold using W3C Actions API
Press and Hold using W3C Mobile Gestures Commands
Press and Hold using TouchAction class

Overview

In the third part of the "Gestures in Appium" series, we will explore how to perform the "Long Press" gesture in Appium. This gesture is typically used to make the item under press draggable or to open modification options like Deletion, Edit, or Select. So, let's dive in!

Press and Hold using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.actions.action_builder import ActionBuilder
from selenium.webdriver.common.actions.pointer_input import PointerInput
from selenium.webdriver.common.actions import interaction

import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.contacts)
driver = webdriver.Remote(appium_server, options=appium_options)

# Find all contacts in the list
contacts = driver.find_elements(by=AppiumBy.ID, value="com.android.contacts:id/cliv_name_textview")

# Create an instance from ActionChains class
actions = ActionChains(driver)

# Create a "touch" type of pointer input. By default it is "mouse"
touch_input = PointerInput(interaction.POINTER_TOUCH, 'touch')

# Override pointer action as 'touch'
actions.w3c_actions = ActionBuilder(self, mouse=touch_input)

# Press and Hold using W3C actions on first contact 
actions.w3c_actions.pointer_action.click_and_hold(contacts[0])
actions.perform()

In this example, we implemented a gesture using W3C Actions API to press and hold the first contact on the list like the one you can see above.
First, we locate all contacts in the list and create an instance of ActionChains to perform actions on them. Next is this:

touch_input = PointerInput(interaction.POINTER_TOUCH, 'touch')

The ActionBuilder class is the key component of W3C Actions, responsible for creating instances of PointerInput, which we talked about in previous parts. The ActionChains class uses this class to create w3c_actions. We have different types of input, such as mouse, touch, wheel, pen, etc. By default, it is set to "mouse". However, in some cases, it is better to change it to "touch", even though the mouse is considered the main input in the appium context (Both 'mouse' and 'touch' are types of pointer actions.). For example, when performing actions like "Zoom", it is mandatory to change the input to "touch".

In this example, although Press and Hold is a type of mouse action, for compatibility reasons, we are changing the input to "touch". Now let's go to the next step:

actions.w3c_actions = ActionBuilder(self, mouse=touch_input)

ActionBuilder has an argument called "mouse" which sets the input type. We are replacing the default input with the one created in the previous step (touch input).

actions.w3c_actions.pointer_action.click_and_hold(contacts[0])
actions.perform()

Finally, we use the click and hold method of the PointerActions class (which is used "ActionBuilder").
I did my best to explain what was happening here. :)

Press and Hold using W3C Mobile Gestures Commands

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.contacts)
driver = webdriver.Remote(appium_server, options=appium_options)
contacts = driver.find_elements(by=AppiumBy.ID, value="com.android.contacts:id/cliv_name_textview")

# Get element coordinates (position in the page)
element_coord = contacts[0].location

# Long press using W3C Mobile Gestures Commands
driver.execute_script('mobile: longClickGesture', {'x': element_coord['x'], 'y': element_coord['y'], 'duration': 1000})

W3C Mobile Gestures has a command mobile: longClickGestures that accepts either element object, coordinates, or selector/locator strategy pair. We simply pass the element's position and set the duration parameter to 1000 milliseconds. So it holds the finger on that position for 1 second.

Press and Hold using TouchAction class [DEPRECATED]

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.contacts)
driver = webdriver.Remote(appium_server, options=appium_options)
contacts = driver.find_elements(by=AppiumBy.ID, value="com.android.contacts:id/cliv_name_textview")

actions = TouchAction(driver)

# actions.long_press(el=contacts[0]).perform()
# or:
actions.press(el=contacts[0]).wait(ms=1000).release().perform()

There are two ways to create a long press gesture in the TouchAction class:

Using long_press method:

actions.long_press(el=contacts[0]).perform()

Or create a sequence of actions to perform it:

actions.press(el=contacts[0]).wait(ms=1000).release().perform()

It is worth mentioning again that you can pass either element object (like we did) or x ,y arguments to the press or long_press methods.

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will cover the Scroll gesture.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 2 - Tap | Double Tap | Multi-finger Tap

Moe Monfared — Sun, 27 Apr 2025 22:51:33 +0000

Overview
Tap (Single | Multi-finger) using W3C Actions API
Double Tap using W3C Mobile Gestures Commands
Double Tap using W3C Actions API
Tap (Single) using TouchAction class [DEPRECTAED]
Tap (Multi-finger) using TouchAction and MultiAction classes [DEPRECTAED]
Double Tap using TouchAction [DEPRECATED]

Overview

In the second part of the "Gestures in Appium" series I will cover all the different methods to perform 'Tap', 'Multi-finger Tap' and 'Double Tap'

What is tapping?

We use our fingers to touch the device. Tapping is quickly touching the device with a bit of pressure, similar to clicking with a mouse.

So what is the difference between Tap, Click, and Press?

Well, Clicking involves using input devices like a Mouse or Trackpad, while on mobile devices, we use our fingers to touch the screen, which is why it's referred to as 'Tap' instead of 'Click'.
'Press' can mean two different things: pressing a keyboard button or holding down on the touch screen. In iOS devices, the amount of pressure applied also matters, as it can perform extra actions on the pressed element.

Tap (Single | Multi-finger) using W3C Actions API

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Controls').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Light Theme').click()

# Tap on Checkbox 1
driver.tap([(0, 596)])

# Multi-finger tap on 5 more coordinations
driver.tap([(0, 840), (0, 1008), (0, 1344), (0, 1456), (0, 1615)])

The driver.tap() is a command associated with the ActionHelpers class which is created using ActionBuilder (specifically ActionChains.w3c_actions()) and is accessible through the driver object. It accepts list of tuples (Up to 5) for positions as the first argument and the duration in milliseconds for the second argument which defines how long the action should be take to perform (default is 100ms).

def tap(self, positions: List[Tuple[int, int]], duration: Optional[int] = None) -> 'WebDriver':

Each tuple represents the point at which the finger should be tapped. To perform a multi-finger tap, you can specify multiple tuples representing the positions of each finger in the list passed to driver.tap()
In the above example, we first tap on (0, 596) which is the coordination of Checkbox 1 . After that, we perform a Multi-finger tap on five more elements.

Double Tap using W3C Mobile Gestures Commands

As mentioned in Part 1, the Mobile Gestures Commands are not only rich but also work perfectly in most cases, making them my favorite! Let's see how simple it is to perform a double tap using these commands:

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Text').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='LogTextBox').click()

# Get element's coordinates (Explained in Part 1)
el_coords = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Add').location

# Perform double tap using mobile gestures commands
driver.execute_script('mobile: doubleClickGesture', {'x': el_coords['x'], 'y': el_coords['y']})

text_el = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/text')
print(text_el.get_attribute('text')) # This is a test \n This is a test

As documented here, we have 3 options to pass. We either should pass the elementId (element object returned from find_element() method), locator and strategy (it will find the element itself) or xand y offset coordinates of the element we want to perform double tap on. In the above example, we retrieve the element's offsets and execute the command by passing them to the command's (x, y) arguments.

Double Tap using W3C Actions API

Unlike the TouchAction class, the ActionHelper (which you’ll see shortly) as of the date of writing this article, W3C Actions API does not currently have a method like double_tap() or a similar parameter like count to specify the number of taps. However, you can simulate a double tap by quickly executing two tap actions. For example:

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Text').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='LogTextBox').click()

# Get elements coordinations (Explained in Part 1)
el_coords = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Add').location

# Perform quickly two taps
driver.tap([(el_coords['x'], el_coords['y'])])
driver.tap([(el_coords['x'], el_coords['y'])])

text_el = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/text')
print(text_el.get_attribute('text')) # This is a test \n This is a test

Tap (Single) using TouchAction class [DEPRECTAED]

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1
from appium.webdriver.common.touch_action import TouchAction

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Controls').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Light Theme').click()

# Create an instance from TouchAction class
action = TouchAction(driver)

# Call the action (tap) and perform
action.tap(x=0, y=596).perform()

To perform actions using the TouchAction class (which is deprecated and removed from Appium), we first need to create an instance of it by passing a driver object to it.

# Create an instance from TouchAction class
action = TouchAction(driver)

Then we call the action we want (which can be chained together, we will see later) and finally, we call the perform() method at the end. We should either pass the coordination (x, y) or element object to the tap() method.

# Call the action (tap) and perform
action.tap(x=0, y=596).perform()

Is it possible to perform a Multi-finger tap using this library? Sure, let's make a hand of fingers!

Tap (Multi-finger) using TouchAction and MultiAction classes [DEPRECTAED]

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
import desired_caps # Explained in Part 1
from appium.webdriver.common.touch_action import TouchAction
from appium.webdriver.common.multi_action import MultiAction

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Views').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Controls').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='1. Light Theme').click()

# Create a instance of TouchAction for each finger
action1 = TouchAction(driver) # Finger 1
action2 = TouchAction(driver) # Finger 2
action3 = TouchAction(driver) # Finger 3

# Call the actions
action1.tap(x=0, y=596)
action2.tap(x=0, y=840)
action3.tap(x=0, y=1008)

# Add and Perform together using MultiAction
multi_action = MultiAction(driver)
multi_action.add(action1, action2, action3)
multi_action.perform()

To perform multi-finger tap using the TouchAction class, we rely on another class called MultiAction which does the magic. Let's break it down into steps:
We start by creating a new instance of the TouchAction class for each finger. (We pass the same driver instance to all of them)

# Create an instance of TouchAction for each finger

action1 = TouchAction(driver) # Finger 1
action2 = TouchAction(driver) # Finger 2
action3 = TouchAction(driver) # Finger 3

Next, we assign an action to each instance, specifying the tapping points for each finger. It is not performed yet.

# Call the actions

action1.tap(x=0, y=596)
action2.tap(x=0, y=840)
action3.tap(x=0, y=1008)

Then we make an instance of the MultiAction class (and pass the driver object to it)

# Create an instance from MultiAction class

multi_action = MultiAction(driver)

Next, using add() method of the MultiAction class, we add all instances of TouchAction object (fingers). It is like a To-Do list of actions that should be performed together.

# Make a hand of fingers :) 

multi_action.add(action1, action2, action3)

Finally, we perform all actions together. They execute simultaneously.

# Perform all actions together
multi_action.perform()

Double Tap using TouchAction [DEPRECATED]

It is quite straightforward to perform a Double Tap using the TouchAction class. The tap() method includes an argument called count which allows you to specify the number of taps you want to perform on the element. As mentioned before you should either pass the element object (element) or a coordination on the page (x and y).

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.touch_action import TouchAction
import desired_caps # Explained in Part 1

appium_server = "http://127.0.0.1:4723"
appium_options = UiAutomator2Options().load_capabilities(desired_caps.apidemos)
driver = webdriver.Remote(appium_server, options=appium_options)
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Text').click()
driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='LogTextBox').click()

action = TouchAction(driver)

# Find the element an assign its object to a value 
el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Add')

# Tapping on it two times (count=2)
action.tap(element=el, count=2).perform()

text_el = driver.find_element(by=AppiumBy.ID, value='io.appium.android.apis:id/text')
print(text_el.get_attribute('text')) # This is a test \n This is a test

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will talk about the Press and Hold (Long-Press) gesture.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

Gestures in Appium - Part 1 - History | Element/Display Rectangular | W3C ActionsAPI

Moe Monfared — Sun, 27 Apr 2025 22:48:33 +0000

What is Appium?
Setup project
Enable “Show Taps” and “Pointer Location”
Get window and element rectangular / size
- Display Rectangular
- Element Rectangular
Calculate the center of an element
W3C Actions API
W3C Mobile Gestures Commands

What is Appium?

Appium is an open-source project and ecosystem designed to facilitate UI automation for a wide range of app platforms, including:

Mobile: iOS, Android, Tizen
Browser: Chrome, Firefox, Safari
Desktop: macOS, Windows
TV: Roku, tvOS, Android TV, Samsung, and more.

In other words, Appium does the same as Selenium but for mobile applications and mobile browsers! With the release of Appium 2.0, it aims to achieve the following primary goals:

Make platform-specific automation capabilities available under a cross-platform, standard API (Compatible with W3C WebDriver protocol).
Allow easy access to this API from any programming language.
Provide tools for convenient community development of Appium extensions.

Appium leverages the WebDriver specification as its API (Including groundbreaking Actions API for its Gestures actions). This choice was influenced by Selenium, a long-standing pioneer in UI automation for web browsers. Selenium's stable API for browser automation served as a solid foundation, and Appium extended it to support mobile apps (iOS and Android). By adopting the WebDriver spec, Appium ensures a unified approach to automation across platforms.

While user interactions on websites and native mobile apps differ, the commonalities in software UIs allow the WebDriver spec to map effectively to any platform. Appium's goal is to provide a consistent experience for developers and testers, regardless of the underlying technology.

In this series of articles, I will explain in detail how to use Appium to perform mobile gestures like zoom, scroll, swipe, drag and drop, and more, using the latest techniques and APIs.

W3C Actions API
W3C Mobile Gestures Actions
UiScrollable Class (Deprecated)
Appium Gestures Plugin
TouchAction | MultiAction (Deprecated, but I will include it just in case to keep the reference)

You will not find all of them in one place except here! So let's get started 🚀

I'll demonstrate how to perform gestures in Android. However, the same libraries also work in iOS with some syntax changes in W3C Mobile Gestures Commands, which I have linked above. (Except Android UiScrollable Class for sure).

Git Repository: All the codes written in this series of articles are pushed to the following repository, so feel free to use it as a reference: automationcamp-appium Github Repo

Setup project

If you haven't installed Appium yet, please follow its official documentation and quick start page. For the demo, we will use the appium official ApiDemos application which you can find in the above repository APK folder or directly from the appium repo. Now:

Create a Python file like appium_gestures.py (test file)
Import all the following classes/libraries. (Look at the comments)

# Main appium driver
from appium import webdriver

# It is used to locate elements
from appium.webdriver.common.appiumby import AppiumBy

# It is used to create a UiAutomator2 driver instance
from appium.options.android import UiAutomator2Options

# W3C compatible gestures helper librart created to update driver's default gestures
from appium.webdriver.extensions.action_helpers import ActionHelpers

# W3C compatible libraries to create any gestures rather than driver's default gestures
from selenium.webdriver.common.actions.action_builder import ActionBuilder
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.actions.mouse_button import MouseButton
from selenium.webdriver.common.actions.pointer_input import PointerInput
from selenium.webdriver.common.actions import interaction

# Old touch action libraries (Deprecated and will remove soon)
from appium.webdriver.common.touch_action import TouchAction
from appium.webdriver.common.multi_action import MultiAction

# It is used to demo purposes. 
from time import sleep

Set the appium server URL globally in the file:

appium_server = "http://127.0.0.1:4723"

Create a file named desired_caps.py in the project root and add the following dictionaries in it:


apidemos = {
    "platformName": "Android",
    "appium:appPackage": "io.appium.android.apis",
    "appium:appActivity": ".ApiDemos",
    "appium:automationName": "UiAutomator2",
}
wdio = {
    "appium:appPackage": "com.wdiodemoapp",
    "appium:appActivity": ".MainActivity",
    "platformName": "Android",
    "appium:automationName": "UiAutomator2"
}
contacts = {
    "appium:appPackage": "com.android.contacts",
    "appium:appActivity": ".activities.PeopleActivity",
    "platformName": "Android",
    "appium:automationName": "UiAutomator2"
}
maps = {
    "appium:appPackage": "com.google.android.apps.maps",
    "appium:appActivity": "com.google.android.maps.MapsActivity",
    "platformName": "Android",
    "appium:automationName": "UiAutomator2"
}
chrome = {
    "platformName": "Android",
    "browserName": "Chrome",
    "appium:options": {
        "automationName": "UiAutomator2",
        # "chromedriverExecutable": "C:/chromedriver.exe"
    }
}

then add the following import statement to the test file.

import desired_caps

Enable "Show Taps" and "Pointer Location"

In automation, it's not possible to see where the gestures are actually being performed. However, there are two options in the "Developer options" that can help us with this.
Show Taps/Touches: By enabling this, you will see a small white dot for each tap.
Pointer Location: This one is even more useful as it shows several things. Firstly, it draws a line for each gesture, making it easier to understand what happened. Secondly, it displays the coordinates (x,y) of the hover, which helps us get the exact location of a specific point on the screen. Finally, it shows the distance performed for X and Y (dX, dY), which can be helpful in determining how far a gesture has moved.

"/>

Get window and element rectangular / size

Doing precise gestures on the display needs interaction with coordination and calculations related to the positions of the elements or display size.
Before diving into gestures we should be aware of them.

Display Rectangular:

In the figure above, the black box represents the Display, which is currently in landscape view. We measure the Size of the Display in pixels (Height/Width), for example, 800px*1440px. Note that this is not the same as the device dimensions, which are measured in inches. The screen size of applications and the display resolution are determined based on display density. Additionally, the app's window may not be entirely maximized, so it could be located anywhere on the screen. The (x,y) coordinates of the top-left corner of this window are referred to as the Location or Coordination.

The following command returns the rectangle of a window, including its X and Y coordinates, as well as its height and width.

window_rect = driver.get_window_rect() # {'height': '800', 'width: '1440', 'x': 100, 'y': 200}

Also, if we just want the Window Size, we can use the following command:

window_rect = driver.get_window_size() # {'height': '800', 'width: '1440'}

Element Rectangular:

Each element within a window has its own rectangular properties, including its Size and Location on the page. The size of an element is defined in terms of its Height and Width in pixels, while its location is determined by measuring the distance from the top-left corner of the screen. To obtain these values, we can use the following method:

# First we find the element and store its object in a value
el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Button')
# Then the "rect" and "location" are what we need:
print(el.rect) # {'height': '100', 'width: '150', 'x': 840, 'y': 680}
print(el.location) # {'x': 840, 'y': 680}

Calculate the center of an element:

If we want to execute a gesture on an element object, we can pass the element object to the relevant command. The driver will automatically perform the gesture at the center of the element. However, if we want to pass the coordinates of the element instead and perform the action on the center, we need to calculate its center point first. This is often necessary as the location attribute returns the coordinates of the element's top-left corner, and we need to determine the center point ourselves. The center point is shown in purple as (x,y) in the above figure.

The following code can be used to do it:

el = driver.find_element(by=AppiumBy.ACCESSIBILITY_ID, value='Button')
center_x = el.rect['x'] + el.rect['width']/2
center_y = el.rect['y'] + el.rect['height']/2

W3C Actions API

Let's take a quick look at the libraries and history of gesture commands. Selenium has its own libraries for mouse actions called "TouchActions" and "ActionChains". While it can handle almost all mouse actions on the web, it may not be completely useful for mobile gesture actions. Therefore, the Appium team had to develop libraries called "TouchAction" and "MultiAction". Let's take a closer look at the comments written by the Appium team at the top of the TouchAction class.

It worked for many years, but in 2018, WebDriver became a W3C standard and introduced the Actions API in section 15 of its specifications. Selenium and its sub-projects, including Appium, must follow these specifications.

By introducing the concepts of Multiple Pointer Inputs and Ticks, it became possible to create almost any gesture by simulating parallel sequences. For instance, you can make a zoom gesture by moving two fingers in opposite directions. You can even draw on the screen! The Appium team explained this concept very well in an article, which you can read to get a better understanding.

W3C Mobile Gestures Commands

We know that in Selenium/Appium, JavaScript commands can be executed using driver.execute_script() , so it opens the door to leveraging the power of JavaScript to perform complex tasks like gestures on the page or app. Thanks to the Appium team, we have a range of commands implemented to perform gestures and they work well in most cases.

mobile: dragGesture
mobile: flingGesture
mobile: doubleClickGesture
mobile: clickGesture
mobile: longClickGesture
mobile: pinchCloseGesture
mobile: pinchOpenGesture
mobile: swipeGesture
mobile: scrollGesture

For iOS: https://appium.readthedocs.io/en/latest/en/writing-running-appium/ios/ios-xctest-mobile-gestures/

A notable advantage of using these commands is their multi-platform compatibility. You can use the same commands with slight change in syntax for both iOS and Android, eliminating the need for driver-specific commands. (UiAutmator2 driver in android and XCUITest driver in iOS ).

So Selenium has implemented W3C actions and updated the ActionChains class, which allows you to use the same class for both Appium and Selenium. You can create your own gestures using this class. Also, there are some official helper classes available for popular gestures using W3C Actions such as driver.swipe() and driver.drag_and_drop() or Mobile Gestures Commands in the latest version of the Appium Python client. We will implement each gesture using all available options in the following articles!

Thank you for taking the time to read! ❤️ 🙏
If you enjoyed the post, please leave your reactions, comments, and questions. I’d love to hear your feedback!

In the next article, we will cover Tap, Multi-Finger Tap, and Double-Tap gestures.

Follow me on LinkedIn: https://www.linkedin.com/in/monfared/

Happy testing ✌️

DEV Community: Moe Monfared

Test Independence Done Right: How to write truly isolated tests!

Overview

The Problem

Ok, Why do we need to solve this problem?

Side note: Environment Isolation

Hooks:

Scope

AAA pattern in test automation:

Now let's see in action: How to make tests independent?

1. Using Setup and Teardown

2. Use dynamic singleton variables - file-scoped or framework-scoped

3. Use random data (string/UUIDs, etc. )

1. Setup / Teardown

Authentication?

Is there any other way instead of using different contexts?

2. Use dynamic variables

2.1 Varibles inside the tests:

2.2 Variables available globally

2.3 Run something before everything else!

3. Use random data (string/UUIDs, etc. )

Random String:

Random valid UUID:

Dynamic locator variable (as mentioned above)

Cypress Test Isolation option:

Gestures in Appium - Part 11 - Use Appium Inspector to Create Gestures

Table of Contents

Overview

What is Appium Inspector?

Creating Pointers

Adding Actions

Saving the Gesture

Running the Gesture on the App

Gestures in Appium - Part 10- Perform gestures in Mobile Web Browsers

Table of Contents

Overview

Set Chrome Driver's binary path

Drag and Drop on Chrome Mobile Browser

Gestures in Appium - Part 9- Plugin

Table of Contents

Overview

Scroll Element Into View (Search) using Gestures Plugin

Drag and Drop using Gestures Plugin

Gestures in Appium - Part 8 - Zoom (Pinch)

Table of Contents

Overview

How to perform Zoom In/out (Pinch Open/Close) in Appium?

Zoom (Pinch) In/Out using W3C Mobile Gestures Commands

Zoom (Pinch) In/Out using Actions API - W3C

Gestures in Appium - Part 7- Drag and Drop

Table of Contents

Overview

What is Drag and Drop?

Drag and Drop using W3C Actions API

Drag and Drop using W3C Mobile Gestures Commands

Gestures in Appium - Part 6- Flick (Fling)

Table of Contents

Overview

Flick (Fling) using W3C Actions API

Flick (Fling) using W3C Mobile Gestures Commands

Gestures in Appium - Part 5 - Swipe (Vertical/Horizontal)

Table of Contents

Overview

What is the difference between Scroll, Swipe, and Flick (Fling)?

Scroll DOWN = Swipe UP?? I'm confused

Swipe Up and Down using W3C Actions API

Swipe Up and Down using W3C Mobile Gestures Commands

Swipe Left and Right using W3C Actions API

Swipe Left and Right using W3C Mobile Gestures Commands

Gestures in Appium - Part 4 - Scroll (Vertical/Horizontal/Search and Scroll Element IntoView)

Table of Contents

Overview

Scroll Up and Down using W3C Actions API

Scroll Up and Down using W3C Mobile Gestures Commands

Scroll using TouchAction class [DEPRECATED]

Scroll Right and Left using W3C Actions API

Scroll Right and Left using W3C Mobile Gestures Commands

Android UiScrollable Class

Scroll Element Into View (Search for element) using Android UiScrollable Class

Scroll Element Into View (Search for element) using W3C Mobile Gestures Commands