[w3c/permissions] Proposed Testing Plan for Geolocation Permission (Issue #460)

marcoscaceres created an issue (w3c/permissions#460)

(ChatGPT generated plan based on the tests we have)

This plan focuses **exclusively** on testing the Permissions API using the `geolocation` permission. By covering the scenarios below, we aim to ensure thorough coverage of how `navigator.permissions.query({ name: 'geolocation' })` behaves, including event firing, revocation, and usage in both Window and Worker contexts.

---

## 1. Event Model Expansion

**Goal**: Verify the `"change"` event for `PermissionStatus` objects works correctly under multiple conditions.

1. **Multiple Listeners**  
   - **Test**: Call `navigator.permissions.query({ name: 'geolocation' })` once, attach two or more listeners:
     ```js
     status.addEventListener('change', /* ... */);
     status.onchange = /* ... */;
     ```
     Then force a state transition from `"prompt"` → `"granted"` (or `"denied"`) using `test_driver.set_permission(...)`.
   - **Check**: Ensure all listeners fire exactly once when the state changes.

2. **Multi-step Transitions**  
   - **Test**: With a single `PermissionStatus`, step through multiple transitions:
     1. **"prompt"** to **"granted"**  
     2. **"granted"** back to **"prompt"** (simulating revocation or expiry)  
     3. **"prompt"** to **"denied"**  
   - **Check**: Each state change fires exactly one `"change"` event, and no event fires if the state is forced to remain the same.

3. **Multiple Watchers**  
   - **Test**: Call `navigator.permissions.query({ name: 'geolocation' })` two or three times. Store each returned `PermissionStatus` in a separate variable, and attach `"change"` listeners to all.  
   - **Check**: When the permission state changes, all watchers receive the `"change"` event.

---

## 2. Worker Context

**Goal**: Ensure `navigator.permissions` behaves as expected in a Worker (i.e., `WorkerNavigator.permissions`).

1. **Basic Query in a Worker**  
   - **Test**: Spin up a dedicated or shared worker, call:
     ```js
     self.navigator.permissions.query({ name: 'geolocation' })
     ```
     and check the returned `PermissionStatus.state`.
   - **Check**: Verify it matches the expected state (e.g., `"prompt"`, `"granted"`, or `"denied"`) depending on how you configure `test_driver.set_permission(...)`.

2. **Event Handling in a Worker**  
   - **Test**: Attach a `"change"` listener to the returned `PermissionStatus`, then force state changes.  
   - **Check**: The `"change"` event fires in the Worker’s context (or is consistently handled according to spec if any constraints apply).

---

## 3. Revocation & Lifetime Expiry

**Goal**: Confirm that *reverting* from `"granted"` to some other state also triggers `"change"` events.

1. **Manual Revocation Simulation**  
   - **Test**: 
     1. `test_driver.set_permission({ name: 'geolocation' }, 'granted')`.  
     2. Call `navigator.permissions.query({ name: 'geolocation' })` to confirm it’s `"granted"`.  
     3. Then forcibly set it to `"prompt"` or `"denied"`:
        ```js
        test_driver.set_permission({ name: 'geolocation' }, 'denied');
        ```
   - **Check**: Confirm the `PermissionStatus` object’s `"change"` event fires. Confirm `status.state` is `"denied"` after the event.

2. **(Optional) Artificial “Expiry”**  
   - If your test environment supports an “expiry-like” scenario, you can replicate it by setting `"granted"` → `"prompt"` after some time. You’d still use `test_driver.set_permission(...)` to automate that transition.

---

## 4. Non–Fully Active Documents

**Goal**: Ensure that a document losing “fully active” status stops receiving permission events and/or throws the appropriate exceptions.

1. **Iframe Removal**  
   - **Test**: Put a script in an iframe that calls `navigator.permissions.query({ name: 'geolocation' })`. Store the `PermissionStatus`, attach a `"change"` listener, then remove the iframe from the DOM.  
   - **Check**: When you call `test_driver.set_permission({ name: 'geolocation' }, 'granted')` afterwards, confirm that the removed iframe’s listener *does not* fire.

2. **Worker in a Removed Iframe**  
   - (If feasible) same idea, but from a Worker in that iframe.

---

## 5. WebDriver Extension Commands

**Goal**: Validate that the user agent’s WebDriver (or BiDi) implementation properly handles the `setPermission` command for geolocation.

1. **Success Path**  
   - **Test**: 
     1. `POST /session/:sessionId/permissions` with:
        ```json
        {
          "descriptor": { "name": "geolocation" },
          "state": "granted"
        }
        ```
     2. Check that the command returns the correct success response (HTTP 200).
     3. Query `navigator.permissions.query({ name: 'geolocation' })` in the same session; expect `"granted"`.

2. **Invalid Argument**  
   - **Test**: 
     1. `POST /session/:sessionId/permissions` with:
        ```json
        {
          "descriptor": { "name": "not-a-real-permission" },
          "state": "granted"
        }
        ```
     2. Expect a 400 “invalid argument” error.  

3. **Unsupported State**  
   - **Test**: If your UA refuses certain states, confirm the same error is returned.

---

## 6. Edge Cases

1. **No Change**  
   - **Test**: Force the same state that’s already in effect—e.g., from `"prompt"` → `"prompt"` again.  
   - **Check**: No `"change"` event fires.

2. **Invalid `PermissionDescriptor`**  
   - **Test**: `navigator.permissions.query({ name: '' })` or some obviously broken descriptor.  
   - **Check**: Must throw `TypeError` or `DOMException("InvalidStateError")` according to the spec rules.

---

## 7. Implementation Notes

- **Automation**: Most tests rely on `test_driver.set_permission({ name: 'geolocation' }, newState)` to transition the permission under test.  
- **Cross-Browser**: Since geolocation is the only permission guaranteed across major browsers, all tests should revolve around `{ name: 'geolocation' }`.  
- **WPT Integration**: Where possible, add these as new `.https.html` or `.https.any.js` files in the `permissions/` folder so they can run automatically in WPT infrastructures.  
- **User Interaction**: The spec has a “prompt the user to choose” algorithm, but it’s not generally automatable. We can rely on direct state changes (like “prompt” → “granted”) via test harness commands.

---

## Summary

These tests—focusing solely on the `geolocation` permission—will expand coverage to include:

- More thorough event model checks (multiple listeners, multiple `PermissionStatus` objects).
- Worker usage tests.
- Revocation and lifetime-like expiration scenarios.
- Proper handling of non–fully active documents.
- Validation of the new WebDriver extension command for permissions.
- Edge case and error-condition testing.

By implementing these scenarios, we achieve a much more robust conformance suite for the Permissions spec as it applies to geolocation.


-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3c/permissions/issues/460
You are receiving this because you are subscribed to this thread.

Message ID: <w3c/permissions/issues/460@github.com>