Installation#

Getting started#

Use pip/conda to install pytest-gee in your environment:

pip install pytest-gee

conda install -c conda-forge pytest-gee

It will then be automatically detected by pytest when you run your test suit.

Connect To Google Earth Engine#

The main purpose of this plugin is to facilitate the connection to Google Earth Engine API in both CI/CD tests and local tests. To do so, the lib will provide a number of connection methods that will hopefully cover your favorite way of connecting to GEE.

Note

If you would like us to code an extra connection method please open an issue on the github repo and never forget that contribution are very welcome!

Note

All the methods presented in this section will fallback to a regular ee.Initialize() if the environment parameter are not found. This means that you can use this plugin in your local environment without having to change anything as long as the ee module is installed and that you already run once ee.Authenticate().

Danger

Never forget that this method can potentially expose your personal credential to GEE so take some safety precautions before starting:

  • make sure the CI/CD platform support private variable (that are not exposed in the build logs)

  • make sure to review PR from new users before starting the build to make sure nobody steal your credentials

  • make sure the account you are using will have access to all the assets you need to run your tests

  • create small tests that will run quickly to make sure you don’t overload your own GEE account with concurrent tasks

Private Token#

The first method is to use a private token. This is the easiest way to connect to GEE in a CI/CD environment.

First authenticate to GEE API in your local computer using ee.Authenticate().

Then copy the credentials file content. This file is located in a different folder depending on the platform you use:

  • Windows: C:\Users\USERNAME\\.config\\earthengine\\credentials

  • Linux: /home/USERNAME/.config/earthengine/credentials

  • MacOS: /Users/USERNAME/.config/earthengine/credentials

Paste this content in your CI/CD environment in a EARTHENGINE_TOKEN variable.

Here is a github action example:

Github action environment variable setup

  1. First go to the settings` of your Github repository

  2. Then to secretes and variables -> Actions

  3. In this page, set a new repository secret with the name EARTHENGINE_TOKEN and paste the content of your credentials file in the value field.

Since earthengine-api v0.1.370, it’s not possible to use EE without providing a GCS project bucket. Save this value in a EARTHENGINE_PROJECT variable, it will be used in the method.

To make the variable available in your CI environment, you will need to add the following line in your action .yaml file:

# .github/action.yaml

env:
    EARTHENGINE_TOKEN: ${{ secrets.EARTHENGINE_TOKEN }}
    EARTHENGINE_PROJECT: ${{ secrets.EARTHENGINE_PROJECT }}

# The rest of your tests configuration

When working in your local environment export a EARTHENGINE_PROJECT variable as well:

export EARTHENGINE_PROJECT=ee-community

Finally you need to configure the pytest execution environment itself. Add the following line in your conftest.py file:

# conftest.py

import pytest_gee


def pytest_configure():
    pytest_gee.init_ee_from_token()

You are now ready to make API calls within your tests!

Service account#

Warning

This documentation assumes that you already have a Google cloud service account and that you have generated an API key for it. If not, please refer to Google own documentation to proceed.

Paste this content of the private-key.json in your CI/CD environment in a EARTHENGINE_SERVICE_ACCOUNT variable.

Here is a github action example:

Github action environment variable setup

  1. First go to the settings of your Github repository

  2. Then to secretes and variables -> Actions

  3. In this page, set a new repository secret with the name EARTHENGINE_SERVICE_ACCOUNT and paste the content of your credentials file in the value field.

Currently when the earthengine-api is Initialized using a service account, the name of the associated cloud project is not detectable. It will prevent the initialization of the test folder generated from pytest-gee. To avoid this issue the method rely also on a EARTHENGINE_PROJECT env variable where you can set the name of your project.

To make the variable available in your CI environment, you will need to add the following line in your action .yaml file:

# .github/action.yaml

env:
    EARTHENGINE_SERVICE_ACCOUNT: ${{ secrets.EARTHENGINE_SERVICE_ACCOUNT }}
    EARTHENGINE_PROJECT: ${{ secrets.EARTHENGINE_PROJECT }}

# The rest of your tests configuration

When working in your local environment export a EARTHENGINE_PROJECT variable as well:

export EARTHENGINE_PROJECT=ee-community

Finally you need to configure the pytest execution environment itself. Add the following line in your conftest.py file:

# conftest.py

import pytest_gee


def pytest_configure():
    pytest_gee.init_ee_from_service_account()

You are now ready to make API calls within your tests!