feat(tests): add e2e test suite

.github/workflows/ci.yml

@@ -7,6 +7,12 @@ on:
   pull_request:
   schedule:
     - cron: "0 8 * * *"
+  workflow_dispatch:
+    inputs:
+      skip_debounce:
+        description: Skip the 5-minute e2e debounce (for urgent re-runs)
+        type: boolean
+        default: false
 
 concurrency:
   group: check-${{ github.ref }}
@@ -98,7 +104,7 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --locked
       - name: Run test suite
-        run: uv run coverage run -m pytest tests
+        run: uv run coverage run -m pytest tests --ignore=tests/e2e
         env:
           COVERAGE_FILE: "coverage.${{ matrix.os }}.${{ matrix.py }}"
       - name: Store coverage file
@@ -143,6 +149,48 @@ jobs:
           name: python-coverage-comment-action
           path: python-coverage-comment-action.txt
 
+  e2e-sandbox:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    permissions:
+      checks: write
+      pull-requests: write
+    if: >
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.draft != true
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - name: Install dependencies
+        run: uv sync --all-extras --locked
+      - name: Debounce
+        # Waits 1 min before running so rapid pushes to the same PR cancel the stale run
+        # (via the global cancel-in-progress) before any e2e work starts.
+        # Skip via the 'quick-e2e' PR label or the skip_debounce workflow_dispatch input.
+        if: >
+          github.event_name == 'pull_request' &&
+          github.actor != 'renovate[bot]' &&
+          !contains(github.event.pull_request.labels.*.name, 'quick-e2e') &&
+          inputs.skip_debounce != 'true'
+        run: sleep 60
+      - name: Run e2e tests
+        if: github.actor != 'renovate[bot]'
+        run: uv run pytest tests/e2e -v -m e2e --junitxml=e2e-report.xml
+        env:
+          DESCOPE_PROJECT_ID: ${{ secrets.DESCOPE_SANDBOX_PROJECT_ID }}
+          DESCOPE_MANAGEMENT_KEY: ${{ secrets.DESCOPE_SANDBOX_MANAGEMENT_KEY }}
+          DESCOPE_BASE_URI: ${{ secrets.DESCOPE_SANDBOX_BASE_URI }}
+      - name: Publish e2e test report
+        if: always() && github.actor != 'renovate[bot]'
+        uses: mikepenz/action-junit-report@3a81627bfac62268172037048872e8ebd4207e6d # v6.4.1
+        with:
+          report_paths: e2e-report.xml
+          check_name: E2E Test Report
+
   gitleaks:
     name: gitleaks
     runs-on: ubuntu-latest
@@ -159,7 +207,7 @@ jobs:
     name: All Checks Passed
     runs-on: ubuntu-latest
     permissions: {}
-    needs: [validate-pr-title, lint, build, coverage, gitleaks]
+    needs: [validate-pr-title, lint, build, coverage, gitleaks, e2e-sandbox]
     if: always() && !cancelled() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled')
     steps:
       - name: Yey, all checks passed!

.gitleaks.toml

@@ -0,0 +1,16 @@
+title = "python-sdk gitleaks config"
+
+[allowlist]
+description = "False positives: test fixture JWTs, coverage artifacts, README examples"
+regexes = [
+    # Fake JWTs used as test fixtures (kid: 2Bt5WLccLUey1Dp7utptZb3Fx9K)
+    '''eyJhbGciOiJFUzM4NCIsImtpZCI6IjJCdDVXTGNjTFVleTFEcDd1dHB0WmIzRng5SyIsInR5cCI6IkpX''',
+    # Fake JWTs used as test fixtures (kid: P2CtzUhdqpIF2ys9gg7ms06UvtC4)
+    '''eyJhbGciOiJFUzM4NCIsImtpZCI6IlAyQ3R6VWhkcXBJRjJ5czlnZzdtczA2VXZ0QzQiLCJ0eXAiOiJK''',
+    # Example password in README docs
+    '''qYlvi65KaX''',
+]
+paths = [
+    # Coverage report artifacts
+    '''htmlcov/''',
+]

.gitleaksignore

@@ -85,6 +85,8 @@ e7f5ad4253ad82236a5cff5f8c06878bfb190b00:tests/test_descope_client.py:jwt:185
 e7f5ad4253ad82236a5cff5f8c06878bfb190b00:tests/test_descope_client.py:jwt:197
 ece761372c78a9ad8a57da5f6d13431d298a99db:tests/test_auth.py:jwt:562
 f3ec873c83a7067a1226d8b712b756b1b599fb3b:tests/test_descope_client.py:jwt:519
+e44fd5977ffd62c56f63c32e2422bf2c0e87c816:tests/test_descope_client_parity.py:jwt:100
+e44fd5977ffd62c56f63c32e2422bf2c0e87c816:tests/test_descope_client_parity.py:jwt:761
 b6a2e217be5dceb6c85332d2e193619894d3a36e:README.md:generic-api-key:1349
 b6a2e217be5dceb6c85332d2e193619894d3a36e:README.md:generic-api-key:1372
 c751b1e9df5dcb6e6b3a62601174065ebf03144f:README.md:generic-api-key:1358

README.md

@@ -575,12 +575,14 @@ except AuthException as e:
 ```
 
 **Important Notes:**
+
 - Verbose mode is **disabled by default** (no performance impact when not needed)
 - When enabled, only the **most recent** HTTP response is stored
 - `get_last_response()` returns `None` when verbose mode is disabled
 - The response object provides dict-like access to JSON data while also exposing HTTP metadata
 
 **Available metadata on response objects:**
+
 - `response.headers` - HTTP response headers (dict-like object)
 - `response.status_code` - HTTP status code (int)
 - `response.text` - Raw response body as text (str)
@@ -1922,6 +1924,33 @@ Running all tests with coverage:
 uv run pytest --junitxml=/tmp/pytest.xml --cov-report=term-missing:skip-covered --cov=descope tests/ --cov-report=xml:/tmp/cov.xml
 ```
 
+### Running e2e tests
+
+The `tests/e2e/` suite exercises the SDK against a real Descope backend. Set the
+following environment variables before running:
+
+| Variable                 | Required | Description                       |
+| ------------------------ | -------- | --------------------------------- |
+| `DESCOPE_PROJECT_ID`     | ✅       | The project to run tests against  |
+| `DESCOPE_MANAGEMENT_KEY` | ✅       | A management key for that project |
+| `DESCOPE_BASE_URI`       | Optional | Override the API base URL         |
+
+**Project prerequisites:** the e2e project must be configured with:
+
+- **Password authentication enabled** with policy: minLength ≥ 9, uppercase required, non-alphanumeric character required (needed by `test_password.py`).
+- **Magic-link / email authentication enabled** (needed by `test_magiclink.py`).
+- **Default flows present** (needed by `test_flow.py`).
+
+```bash
+uv run pytest tests/e2e -v
+```
+
+To run the full test suite while skipping e2e tests (default CI behaviour):
+
+```bash
+uv run pytest tests -m "not e2e"
+```
+
 ### Lint and format
 
 ```bash

descope/__init__.py

@@ -10,6 +10,7 @@
     SignUpOptions,
 )
 from descope.descope_client import DescopeClient
+from descope.descope_client_async import DescopeClientAsync
 from descope.exceptions import (
     API_RATE_LIMIT_RETRY_AFTER_HEADER,
     ERROR_TYPE_API_RATE_LIMIT,
@@ -64,6 +65,7 @@
     "DeliveryMethod",
     "LoginOptions",
     "SignUpOptions",
+    "DescopeClientAsync",
     "DescopeClient",
     "API_RATE_LIMIT_RETRY_AFTER_HEADER",
     "ERROR_TYPE_API_RATE_LIMIT",