chore: modernize prod server integration tests

.gitignore

@@ -7,6 +7,7 @@ lcov.info
 test-results.xml
 tmp/
 .env*
+!.env.sample
 
 # npm pack outputs
 *.tgz

biome.json

@@ -10,6 +10,7 @@
   "files": {
     "includes": [
       "packages/**",
+      "prod-server-integration-tests/**",
       "!!packages/client",
       "!!packages/events-api",
       "!!packages/interactive-messages"

prod-server-integration-tests/.env.sample

@@ -0,0 +1,105 @@
+# =============================================================================
+# Production Server Integration Tests - Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in the values.
+# The dotenv package loads .env automatically when tests run.
+#
+# Each variable references which manifest/app it corresponds to.
+# See manifests/ directory for app configurations.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Main Bot App (see manifests/main-bot-app.manifest.json)
+# Install this app to your test workspace with all listed bot + user scopes.
+# -----------------------------------------------------------------------------
+
+# Bot token (xoxb-) from the main bot app
+# Used by: test/web-api.js, test/bookmarks-web-api.js, scripts/conversations_invite.js,
+#          scripts/auth_test.js, scripts/pagination.js
+SLACK_SDK_TEST_BOT_TOKEN=xoxb-your-bot-token
+
+# User token (xoxp-) from the main bot app (user must authorize the app)
+# Used by: test/web-api.js
+SLACK_SDK_TEST_USER_TOKEN=xoxp-your-user-token
+
+# A public channel ID in the test workspace (bot must be a member)
+# Used by: test/web-api.js (chat.scheduleMessage tests)
+SLACK_SDK_TEST_WEB_TEST_CHANNEL_ID=C0123456789
+
+# -----------------------------------------------------------------------------
+# Slack Connect Apps (see manifests/slack-connect-sender.manifest.json
+#                     and manifests/slack-connect-receiver.manifest.json)
+# These require TWO separate workspaces with Slack Connect enabled.
+# A shared channel must be manually created between the two workspaces
+# with both bots added as members before running tests.
+# -----------------------------------------------------------------------------
+
+# Bot token for the SENDER workspace app
+# Used by: test/web-api.js (Slack Connect tests)
+SLACK_SDK_TEST_CONNECT_INVITE_SENDER_BOT_TOKEN=xoxb-sender-bot-token
+
+# Bot token for the RECEIVER workspace app
+# Used by: test/web-api.js (Slack Connect tests)
+SLACK_SDK_TEST_CONNECT_INVITE_RECEIVER_BOT_TOKEN=xoxb-receiver-bot-token
+
+# The bot user ID (not the app ID) of the receiver bot (starts with U or W)
+# Used by: test/web-api.js (Slack Connect tests)
+SLACK_SDK_TEST_CONNECT_INVITE_RECEIVER_BOT_USER_ID=U0123456789
+
+# -----------------------------------------------------------------------------
+# Enterprise Grid Admin Tokens (see manifests/admin-app.manifest.json)
+# These are USER tokens (xoxp-) from admin users in an Enterprise Grid org.
+# The app must be installed org-wide with admin scopes granted.
+# -----------------------------------------------------------------------------
+
+# Team ID of the PRIMARY workspace in the Enterprise Grid org
+# Required by conversations.create when using Enterprise Grid tokens
+# Used by: test/admin-web-api-conversations-bulk.js, test/admin-web-api-custom-retention.js
+SLACK_SDK_TEST_GRID_WORKSPACE_ID=T0123456789
+
+# Org-level admin user token (org admin of the Enterprise Grid)
+# Used by: all admin test files (test/admin-web-api*.js),
+#          scripts/admin/usersSessionSettings.js
+SLACK_SDK_TEST_GRID_ORG_ADMIN_USER_TOKEN=xoxp-org-admin-token
+
+# Team ID of a SECONDARY workspace in the same Enterprise Grid org
+# (must differ from the primary workspace above)
+# Used by: test/admin-web-api-conversations-bulk.js (bulkMove test)
+SLACK_SDK_TEST_GRID_SECONDARY_WORKSPACE_ID=T0123456789
+
+# (Optional) A user ID for auth policy tests
+# Used by: test/admin-web-api.js (admin.auth.policy tests)
+# SLACK_SDK_TEST_GRID_USER_ID=U0123456789
+
+# -----------------------------------------------------------------------------
+# Socket Mode App (see manifests/socket-mode-app.manifest.json)
+# This app must have Socket Mode enabled in app settings.
+# Generate an app-level token with connections:write scope.
+# -----------------------------------------------------------------------------
+
+# App-level token (xapp-) with connections:write scope
+# Used by: scripts/socket-mode.js
+SLACK_SDK_TEST_SOCKET_MODE_APP_TOKEN=xapp-your-app-level-token
+
+# -----------------------------------------------------------------------------
+# Scripts - Additional Tokens
+# Some scripts use alternate variable names for convenience.
+# -----------------------------------------------------------------------------
+
+# (Optional) A user ID for pagination script filtering
+# Used by: scripts/pagination.js
+# SLACK_USER_ID=U0123456789
+
+# -----------------------------------------------------------------------------
+# App Manifest Lifecycle (tooling/configuration token)
+# This is NOT an app-specific token. Generate via App Configuration Tokens:
+# https://api.slack.com/authentication/config-tokens
+# -----------------------------------------------------------------------------
+
+# Configuration/tooling token for apps.manifest.* API methods
+# Used by: scripts/apps_manifest_test.js
+SLACK_TOOLING_TOKEN=xoxe-your-tooling-token
+
+# (Optional) Override the Slack API base URL (for dev/staging environments)
+# Used by: scripts/apps_manifest_test.js
+# SLACK_SDK_TEST_DEV_API_URL=https://dev.slack.com/api/

prod-server-integration-tests/README.md

@@ -1,33 +1,98 @@
-First off, you need to link `@slack/*` packages to `../packages/*` to verify the latest revision's behavior.
+# Production Server Integration Tests
+
+End-to-end integration tests that run against real Slack APIs to verify the
+`@slack/web-api` and `@slack/socket-mode` packages work correctly.
+
+## Prerequisites
+
+1. **Build local packages** that these tests depend on:
+
+```bash
+npm run build
+```
+
+2. **Install dependencies**:
 
 ```bash
-./link-web-api.sh
+npm install
 ```
 
-If you would like to run `scripts/socket-mode.js` with the latest revision of code in this repo, run `./link-socket-mode.sh` instead.
+3. **Create the required Slack apps** using the manifests in [`manifests/`](./manifests/).
+   See [`manifests/README.md`](./manifests/README.md) for detailed setup instructions.
 
-### How to run tests
+4. **Configure environment variables** by copying the sample file:
 
 ```bash
-# with all of the bot scopes
-export SLACK_SDK_TEST_BOT_TOKEN=xoxb-
-# with all of the user scopes
-export SLACK_SDK_TEST_USER_TOKEN=xoxp-
-# admin user's token for a workspace in an Enterprise Grid org
-export SLACK_SDK_TEST_GRID_WORKSPACE_ADMIN_USER_TOKEN=xoxp-
-# org-level admin user's token
-export SLACK_SDK_TEST_GRID_ORG_ADMIN_USER_TOKEN=xoxp-
-# admin user's token for a secondary workspace in an Enterprise Grid org (must be in same org as workspace for SLACK_SDK_TEST_GRID_WORKSPACE_ADMIN_USER_TOKEN, but a different workspace) - required for admin.conversations.bulkMove test
-export SLACK_SDK_TEST_GRID_SECONDARY_WORKSPACE_ID=T0123456789
+cp .env.sample .env
+# Edit .env and fill in your tokens/IDs
+```
 
+## Running Tests
+
+### All tests
+
+```bash
 npm test
 ```
 
-### How to run example scripts
+### Individual test suites
 
 ```bash
-# some examples may use different env variable names
-export SLACK_BOT_TOKEN=xoxb-(your own token)
-# Run the script
-npx node scripts/pagination.js # or whatever you want to run
+# Core Web API tests (auth, chat.scheduleMessage, Slack Connect, team.*)
+node --test-timeout=10000 --test test/web-api.test.js
+
+# Bookmarks CRUD
+node --test-timeout=10000 --test test/bookmarks-web-api.test.js
+
+# Admin: session settings + auth policy
+node --test-timeout=10000 --test test/admin-web-api.test.js
+
+# Admin: analytics
+node --test-timeout=10000 --test test/admin-web-api-analytics.test.js
+
+# Admin: bulk archive/delete/move
+node --test-timeout=10000 --test test/admin-web-api-conversations-bulk.test.js
+
+# Admin: custom retention
+node --test-timeout=10000 --test test/admin-web-api-custom-retention.test.js
+
+# Admin: roles
+node --test-timeout=10000 --test test/admin-web-api-roles.test.js
+
+# Admin: user sessions reset
+node --test-timeout=10000 --test test/admin-web-api-user-sessions.test.js
+
+# Admin: unsupported versions export
+node --test-timeout=10000 --test test/admin-web-api-users-unsupportedVersions-export.test.js
 ```
+
+### Example scripts
+
+```bash
+# No token needed
+node scripts/api_test.js
+
+# Requires SLACK_SDK_TEST_BOT_TOKEN
+node scripts/auth_test.js
+node scripts/pagination.js
+node scripts/conversations_invite.js
+
+# Requires SLACK_SDK_TEST_SOCKET_MODE_APP_TOKEN
+node scripts/socket-mode.js
+
+# Requires SLACK_TOOLING_TOKEN
+node scripts/apps_manifest_test.js
+
+# Requires SLACK_SDK_TEST_GRID_*_TOKEN vars
+node scripts/admin/usersSessionSettings.js
+```
+
+## Environment Variables
+
+See [`.env.sample`](./.env.sample) for the complete list with descriptions.
+
+## App Manifests
+
+The [`manifests/`](./manifests/) directory contains ready-to-use app manifest JSON files.
+Each file can be pasted directly into the Slack app creation flow at
+[api.slack.com/apps](https://api.slack.com/apps) when selecting "From an app manifest."

prod-server-integration-tests/logger.js

@@ -0,0 +1,43 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const SEVERITY = { debug: 100, info: 200, warn: 300, error: 400 };
+
+export class FileLogger {
+  #level;
+  #filePath;
+
+  constructor(filePath, level = 'debug') {
+    this.#filePath = filePath;
+    this.#level = level;
+    mkdirSync(dirname(filePath), { recursive: true });
+  }
+
+  getLevel() {
+    return this.#level;
+  }
+  setLevel(level) {
+    this.#level = level;
+  }
+  setName(_name) {}
+
+  debug(...msg) {
+    this.#log('debug', msg);
+  }
+  info(...msg) {
+    this.#log('info', msg);
+  }
+  warn(...msg) {
+    this.#log('warn', msg);
+  }
+  error(...msg) {
+    this.#log('error', msg);
+  }
+
+  #log(level, msg) {
+    if (SEVERITY[level] >= SEVERITY[this.#level]) {
+      const entry = JSON.stringify({ level, message: msg.length === 1 ? msg[0] : msg });
+      appendFileSync(this.#filePath, `${entry}\n`);
+    }
+  }
+}

prod-server-integration-tests/manifests/README.md

@@ -0,0 +1,40 @@
+# App Manifests for Integration Tests
+
+This directory contains example `manifest.json` files for the Slack apps required
+to run the production integration tests.
+
+## Overview
+
+| Manifest File | Purpose | Token Env Variable(s) |
+|---|---|---|
+| `main-bot-app.manifest.json` | Primary bot for Web API tests | `SLACK_SDK_TEST_BOT_TOKEN`, `SLACK_SDK_TEST_USER_TOKEN` |
+| `slack-connect-sender.manifest.json` | Slack Connect sender workspace bot | `SLACK_SDK_TEST_CONNECT_INVITE_SENDER_BOT_TOKEN` |
+| `slack-connect-receiver.manifest.json` | Slack Connect receiver workspace bot | `SLACK_SDK_TEST_CONNECT_INVITE_RECEIVER_BOT_TOKEN` |
+| `socket-mode-app.manifest.json` | Socket Mode listener | `SLACK_SDK_TEST_SOCKET_MODE_APP_TOKEN` |
+| `admin-app.manifest.json` | Enterprise Grid admin operations | `SLACK_SDK_TEST_GRID_ORG_ADMIN_USER_TOKEN` |
+
+## How to Use These Manifests
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** > **From an app manifest**
+3. Select the target workspace
+4. Paste the contents of the relevant manifest file (choose JSON format)
+5. Review and create the app
+6. Install the app to the workspace and note the generated tokens
+
+### Special Setup
+
+**Slack Connect tests** require two apps in two *different* workspaces that both have
+Slack Connect enabled. You must manually create a shared channel between the two
+workspaces and add both bots as members before running the tests.
+
+**Admin tests** require an Enterprise Grid organization. The admin app must be
+installed at the org level by an Org Admin. The user tokens (`xoxp-`) come from
+admin users who authorize the app — these are not bot tokens.
+
+**Socket Mode app** requires generating an app-level token with `connections:write`
+scope after creating the app. Go to **App Settings > Basic Information > App-Level Tokens**
+to generate this token (`xapp-`).
+
+**Tooling token** (`SLACK_TOOLING_TOKEN`) is a configuration token not associated
+with any of these manifests. Generate it via the [App Configuration Tokens](https://api.slack.com/authentication/config-tokens) flow.

prod-server-integration-tests/manifests/admin-app.manifest.json

@@ -0,0 +1,40 @@
+{
+  "_metadata": {
+    "major_version": 1,
+    "minor_version": 1
+  },
+  "display_information": {
+    "name": "Node SDK Admin Tests",
+    "description": "Admin app for Enterprise Grid integration tests. Must be installed org-wide by an Org Admin."
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "SDK Admin Test Bot",
+      "always_online": false
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": ["channels:manage", "channels:read", "users:read"],
+      "user": [
+        "admin.analytics:read",
+        "admin.conversations:read",
+        "admin.conversations:write",
+        "admin.roles:read",
+        "admin.roles:write",
+        "admin.users:read",
+        "admin.users:write",
+        "channels:write",
+        "groups:write",
+        "mpim:write",
+        "im:write",
+        "users:read"
+      ]
+    }
+  },
+  "settings": {
+    "org_deploy_enabled": true,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false
+  }
+}