From 06b86c385b26c76921a9dd05d8cac754b4e3cef3 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 19 Aug 2024 22:04:50 -0500 Subject: [PATCH 1/5] Update slack.mdx --- docs/guides/cloud/integrations/slack.mdx | 228 +++++++---------------- 1 file changed, 67 insertions(+), 161 deletions(-) diff --git a/docs/guides/cloud/integrations/slack.mdx b/docs/guides/cloud/integrations/slack.mdx index e16e9f243f..26dcba3333 100644 --- a/docs/guides/cloud/integrations/slack.mdx +++ b/docs/guides/cloud/integrations/slack.mdx @@ -1,76 +1,52 @@ --- -title: Integration for Slack +title: Cypress App for Slack sidebar_position: 40 sidebar_label: Slack --- -The Cypress integration for Slack allows you to see your Cypress test results -directly in your teams' Slack channels. +One of our most-requested Cypress Cloud features to date, the Cypress app for Slack provides real-time results for your Cypress tests, all in one place—improving remote collaboration and giving wider visibility into test behavior and Application Quality. - +The Cypress app for Slack allows you to: +- Improve cross-team collaboration by instantly surfacing Cypress results to the teams that need visibility +- Confirm that key tests pass prior to launching new products or features +- Reduce the time it takes to catch failed tests -## Install the Cypress integration for Slack + -:::caution +## Getting started +You need just three things to get started: -Ownership Requirements +- Cypress Cloud account +- Ability to configure Cypress Cloud integrations - You must be an admin or owner of your Cypress Cloud organization . +- Ability to authorize Slack apps - By default, Slack allows any workspace member to authorize apps, however workspace owners may require app approvals before installation. See this [Slack help article](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace) for more details. -In order to install the Cypress integration for Slack, you must be an admin or -owner of both your Cypress Cloud organization and your Slack workspace. +### Install the Cypress app for Slack -::: +1. In the Cypress Cloud, visit the Integrations page for the organization you wish to integrate with Slack. +2. Click the **Enable** button in the Slack section. +3. A popup window will be displayed requesting permission for Cypress to access the + workspace. +4. After you approve the app permissions, you can choose your Slack workspace and channel to + associate with the installation. +4. The installation is complete! -**To install the Cypress integration for Slack:** +Now Cypress will post run results for all projects in your organization to the specified Slack channel. -1. Go to Cypress Cloud - [Organizations page](https://cloud.cypress.io/organizations) or open the - organization switcher. -2. Select the organization you wish to integrate with Slack. +## Slack configuration - +The Slack messages can be tailor to match your teams' needs. -3. Visit the selected organization's **Integrations** page via the side - navigation. +- The Slack app can send results to one or more public or private Slack channels or directly to a specific user +- You can select your notification preferences that should be posted. +- The app can be configured at the orginazation-level, as well as at the project-level, to support organizations with multiple teams working on separate projects. - +### Slack channels -4. Click the **Enable** button in the Slack section. - - - -5. You'll see a popup window that requests permission for Cypress to access the - workspace and allows you to choose your Slack workspace and channel to - associate with the installation. Once you've selected a channel and allowed - access, the installation is complete! Cypress Cloud will post run results for - all projects in your organization to the specified Slack channel. - -For more information about how the Cypress integration for Slack collects and -manages your information, please visit our -[Privacy Policy](https://on.cypress.io/privacy-policy). - -## Per-organization configuration - -### Add additional Slack channels - -You can have Cypress Cloud post run results to an additional channels. To add a +You can have Cypress Cloud post run results to specific channels. To add a channel: +....global vs private configuration + 1. Navigate to the **Integrations** page for the organization with the installed integration. 2. Within the Slack integration, click **Configure**. @@ -79,147 +55,57 @@ channel: with the organization. Cypress Cloud will post run results for all projects in your organization to the new Slack channel. -### Set notification preferences - -By default, Cypress Cloud will post a Slack message to each configured channel -only for failing runs. If you'd like to change these preferences: - -1. Navigate to the **Integrations** page for the organization with the installed - integration. -2. Within the Slack integration, click **Configure**. -3. Under **Notifications**, select your preference for each Slack channel: - -- **Failed runs**: will notify on runs with a failed status. -- **Passed runs**: will notify on runs with a passed status. -- **Flaky tests**: will notify on runs that have an identified flaky test. - -### Mute a channel - -If you want Cypress Cloud to temporarily stop posting Slack messages to a -certain channel, you can **Mute** that channel. This allows you to easily pause -and resume notifications for a specific channel without losing the configuration -you've put in place. - -1. Navigate to the **Integrations** page for the organization with the installed - integration. -2. Within the Cypress integration for Slack, click **Configure**. -3. Under **Actions**, select your **Mute** for each Slack channel you want - muted. - -### Remove a Slack channel - -You can have Cypress Cloud stop posting notifications to a channel. You can -remove all Slack channels if you'd prefer to disable global notifications -altogether in favor of per-project notifications. +### Direct Messages -1. Navigate to the **Integrations** page for the organization with the installed - integration. -2. Within the Cypress integration for Slack, click **Configure**. -3. Under **Actions**, select your **Delete** for each Slack channel you want - deleted. +.... -## Per-project configuration - -If your organization has multiple teams working on separate projects, you can -tailor the Slack notifications of each project to match your teams' needs. - -### Add a new Slack channel - -You can have Cypress Cloud post run results for a specific project to an -additional channel. - -1. Select your organization in the organization switcher. - -2. Select the project you wish to integrate with Slack. - -3. Go to the project's settings page. - -4. Scroll down to the **Slack Integration** section. -5. Click **Add Slack Channel**. -6. You'll see a popup window that allows you to choose the channel to associate - with the project. - -### Set notification preferences +### Notification preferences By default, Cypress Cloud will post a Slack message to each configured channel -only for failing runs. - -If you'd like to change these preferences: - -1. Navigate to the **Integrations** page for the project with the installed - integration. -2. Scroll down to the **Slack Integration** section. -3. Under **Notifications**, select your preference for each Slack channel: +only for failing runs. However, you can select any combination of the followings preferences: - **Failed runs**: will notify on runs with a failed status. - **Passed runs**: will notify on runs with a passed status. - **Flaky tests**: will notify on runs that have an identified flaky test. -:::info +#### Filter notifications by tag -You cannot override the notification preferences for globally configured Slack -integrations. - -::: - -### Filter notifications by tag - -You can filter notifications posted to Slack based on a +When configuring at the project-level, you can filter notifications posted to Slack based on a [tag](/guides/guides/command-line#cypress-run-tag-lt-tag-gt) the run was recorded with. This can be helpful to only post notifications on certain runs, like those to a staging or release environment. -1. Navigate to the **Integrations** page for the project with the installed - integration. -2. Scroll down to the **Slack Integration** section. +1. Navigate to the **Slack Integration** section in the Integrations tab of your Project's Settings. 3. Under **Tags**, select the **Tag** dropdown for the desired integration and select which tag to filter. -:::info - -Filtering by tags is only available on integrations configured at the project -level. - -::: ### Mute a channel If you want Cypress Cloud to temporarily stop posting Slack messages to a certain channel, you can **Mute** that channel. This allows you to easily pause and resume notifications for a specific channel without losing the configuration -you've put in place. You can even mute the messages for the global organization -channels! +you've put in place. -1. Navigate to the **Integrations** page for the project with the installed +1. Navigate to the **Integrations** page for the organization with the installed integration. -2. Scroll down to the **Slack Integration** section. +2. Within the Cypress integration for Slack, click **Configure**. 3. Under **Actions**, select your **Mute** for each Slack channel you want muted. -### Remove a channel +### Remove a Slack channel -You can have Cypress Cloud stop posting notifications to a channel. You cannot -delete the global notification channels from a project. +You can have Cypress Cloud stop posting notifications to a channel. You can +remove all Slack channels if you'd prefer to disable global notifications +altogether in favor of per-project notifications. -1. Navigate to the **Integrations** page for the project with the installed +1. Navigate to the **Integrations** page for the organization with the installed integration. -2. Scroll down to the **Slack Integration** section. +2. Within the Cypress integration for Slack, click **Configure**. 3. Under **Actions**, select your **Delete** for each Slack channel you want deleted. -## Remove the integration +### Remove the integration You can completely remove the Cypress integration for Slack from your workspace. This will remove the @cypress bot from your workspace and will delete all of the @@ -231,3 +117,23 @@ will be able to install the Cypress integration for Slack again in the future. 2. Within the Slack Integration, click **Configure**. 3. Click **Uninstall Slack Integration** to uninstall the Cypress integration for Slack. + +## Security and Compliance + +Review our [Privacy Policy](https://on.cypress.io/privacy-policy) for information about how the Cypress app for Slack collects and +manages your information. + +### Authorizations +On behalf of users, Cypress can: + - View information about a user’s identity + - Show previews of cloud.cypress.io URLs in messages + - View URLs from cloud.cypress.io + +On behalf of the app, Cypress can: + - Post messages to specific channels in Slack & direct message conversations + - Show previews of cloud.cypress.io URLs in messages + - View URLs from cloud.cypress.io + +### App scopes +- User token scopes: `links:read`, `links:write` +- Bot token scopes: `chat:write`, `incoming-webhook`, `links:read`, `links:write` From e81fcefa612772bd3fbc0cad117f4a0b4fde3932 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Tue, 24 Sep 2024 12:52:05 -0500 Subject: [PATCH 2/5] slack docs updates --- docs/guides/cloud/integrations/slack.mdx | 93 ++++++++++++++---------- 1 file changed, 55 insertions(+), 38 deletions(-) diff --git a/docs/guides/cloud/integrations/slack.mdx b/docs/guides/cloud/integrations/slack.mdx index 26dcba3333..a56434f0b8 100644 --- a/docs/guides/cloud/integrations/slack.mdx +++ b/docs/guides/cloud/integrations/slack.mdx @@ -4,23 +4,23 @@ sidebar_position: 40 sidebar_label: Slack --- -One of our most-requested Cypress Cloud features to date, the Cypress app for Slack provides real-time results for your Cypress tests, all in one place—improving remote collaboration and giving wider visibility into test behavior and Application Quality. +One of our most-requested Cypress Cloud features, the Cypress app for Slack provides real-time results for your Cypress tests, all in one place—improving remote collaboration and giving wider visibility into test behavior and Application Quality. The Cypress app for Slack allows you to: - Improve cross-team collaboration by instantly surfacing Cypress results to the teams that need visibility - Confirm that key tests pass prior to launching new products or features - Reduce the time it takes to catch failed tests - + ## Getting started You need just three things to get started: - Cypress Cloud account -- Ability to configure Cypress Cloud integrations - You must be an admin or owner of your Cypress Cloud organization . -- Ability to authorize Slack apps - By default, Slack allows any workspace member to authorize apps, however workspace owners may require app approvals before installation. See this [Slack help article](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace) for more details. +- Ability to configure Cypress Cloud integrations - you must be an admin or the owner of your Cypress Cloud organization. +- Ability to authorize Slack apps - by default, Slack allows any workspace member to authorize apps, however workspace owners may require app approvals before installation. See this [Slack help article](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace) for more details. -### Install the Cypress app for Slack +## Install the Cypress app for Slack 1. In the Cypress Cloud, visit the Integrations page for the organization you wish to integrate with Slack. 2. Click the **Enable** button in the Slack section. @@ -34,30 +34,52 @@ Now Cypress will post run results for all projects in your organization to the s ## Slack configuration -The Slack messages can be tailor to match your teams' needs. +The Slack messages can be tailored to match your teams' needs. - The Slack app can send results to one or more public or private Slack channels or directly to a specific user -- You can select your notification preferences that should be posted. -- The app can be configured at the orginazation-level, as well as at the project-level, to support organizations with multiple teams working on separate projects. +- You can select your notification preferences for when and where run results should be posted. +- The app can be configured at the organization-level and project-level which supports multiple teams working on separate projects. + +### Per-Organization vs per-project configuration + +The following describes where to go to configure Slack for an organization and a project. The remaining sections will describe the supported configuration options. + +#### Organization settings +To share Slack configuration for an organization: +1. Navigate to the Integrations page for the organization you wish to configure. +2. Within the Slack integration, click Configure. +3. Configure the app. + +#### Project settings +To share Slack configuration for a project: +1. Navigate to the Project Settings page for the project you wish to configure. +2. Click on the Integrations tab within the Project Settings page. +3. Configure the app with the Slack Integration section. ### Slack channels You can have Cypress Cloud post run results to specific channels. To add a channel: -....global vs private configuration +1. Navigate to the Slack configuration page +2. Click **Add Slack Channel**. +3. You'll see a popup window that allows you to choose the channel or individual associate + with the organization. +4. Search for and selecting the channel messages should post to. -1. Navigate to the **Integrations** page for the organization with the installed - integration. -2. Within the Slack integration, click **Configure**. -3. Click **Add Slack Channel**. -4. You'll see a popup window that allows you to choose the channel to associate - with the organization. Cypress Cloud will post run results for all projects - in your organization to the new Slack channel. +Cypress Cloud will begin to post run results to the channel. + +### Direct messages + +You can have Cypress Cloud post run results to specific user. To post to a user: -### Direct Messages +1. Navigate to the Slack configuration page +2. Click **Add Slack Channel**. +3. You'll see a popup window that allows you to choose the channel or individual associate + with the organization. +4. Search for and selecting the user that messages should be sent to. -.... +Cypress Cloud will begin to send run results to the this user. ### Notification preferences @@ -68,6 +90,9 @@ only for failing runs. However, you can select any combination of the followings - **Passed runs**: will notify on runs with a passed status. - **Flaky tests**: will notify on runs that have an identified flaky test. +1. Navigate to Slack configuration page +2. Select the notification preferences for each channel + #### Filter notifications by tag When configuring at the project-level, you can filter notifications posted to Slack based on a @@ -75,11 +100,10 @@ When configuring at the project-level, you can filter notifications posted to Sl recorded with. This can be helpful to only post notifications on certain runs, like those to a staging or release environment. -1. Navigate to the **Slack Integration** section in the Integrations tab of your Project's Settings. -3. Under **Tags**, select the **Tag** dropdown for the desired integration and +1. Navigate to the Slack configuration page +2. Under **Tags**, select the **Tag** dropdown for the desired integration and select which tag to filter. - ### Mute a channel If you want Cypress Cloud to temporarily stop posting Slack messages to a @@ -87,10 +111,8 @@ certain channel, you can **Mute** that channel. This allows you to easily pause and resume notifications for a specific channel without losing the configuration you've put in place. -1. Navigate to the **Integrations** page for the organization with the installed - integration. -2. Within the Cypress integration for Slack, click **Configure**. -3. Under **Actions**, select your **Mute** for each Slack channel you want +1. Navigate to the Slack configuration page +2. Under **Actions**, select your **Mute** for each Slack channel you want muted. ### Remove a Slack channel @@ -99,16 +121,14 @@ You can have Cypress Cloud stop posting notifications to a channel. You can remove all Slack channels if you'd prefer to disable global notifications altogether in favor of per-project notifications. -1. Navigate to the **Integrations** page for the organization with the installed - integration. -2. Within the Cypress integration for Slack, click **Configure**. -3. Under **Actions**, select your **Delete** for each Slack channel you want +1. Navigate to the Slack configuration page +2. Under **Actions**, select your **Delete** for each Slack channel you want deleted. -### Remove the integration +## Remove the integration You can completely remove the Cypress integration for Slack from your workspace. -This will remove the @cypress bot from your workspace and will delete all of the +This will remove the `@cypress` bot from your workspace and will delete all of the Slack configurations you've set in Cypress Cloud. You cannot undo this, but you will be able to install the Cypress integration for Slack again in the future. @@ -118,20 +138,17 @@ will be able to install the Cypress integration for Slack again in the future. 3. Click **Uninstall Slack Integration** to uninstall the Cypress integration for Slack. -## Security and Compliance +## Security and compliance Review our [Privacy Policy](https://on.cypress.io/privacy-policy) for information about how the Cypress app for Slack collects and manages your information. ### Authorizations -On behalf of users, Cypress can: - - View information about a user’s identity - - Show previews of cloud.cypress.io URLs in messages - - View URLs from cloud.cypress.io -On behalf of the app, Cypress can: +When authorized, Cypress can: + - View information about a user’s identity - Post messages to specific channels in Slack & direct message conversations - - Show previews of cloud.cypress.io URLs in messages + - Show previews of cloud.cypress.io URLs in messages - View URLs from cloud.cypress.io ### App scopes From 13d71b31c4cd0b83daeffdd71b9367e1cd71324e Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Tue, 24 Sep 2024 13:01:01 -0500 Subject: [PATCH 3/5] run prettier --- docs/guides/cloud/integrations/slack.mdx | 25 +++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/guides/cloud/integrations/slack.mdx b/docs/guides/cloud/integrations/slack.mdx index a56434f0b8..446b743b55 100644 --- a/docs/guides/cloud/integrations/slack.mdx +++ b/docs/guides/cloud/integrations/slack.mdx @@ -7,13 +7,18 @@ sidebar_label: Slack One of our most-requested Cypress Cloud features, the Cypress app for Slack provides real-time results for your Cypress tests, all in one place—improving remote collaboration and giving wider visibility into test behavior and Application Quality. The Cypress app for Slack allows you to: + - Improve cross-team collaboration by instantly surfacing Cypress results to the teams that need visibility - Confirm that key tests pass prior to launching new products or features - Reduce the time it takes to catch failed tests - + ## Getting started + You need just three things to get started: - Cypress Cloud account @@ -28,7 +33,7 @@ You need just three things to get started: workspace. 4. After you approve the app permissions, you can choose your Slack workspace and channel to associate with the installation. -4. The installation is complete! +5. The installation is complete! Now Cypress will post run results for all projects in your organization to the specified Slack channel. @@ -38,20 +43,24 @@ The Slack messages can be tailored to match your teams' needs. - The Slack app can send results to one or more public or private Slack channels or directly to a specific user - You can select your notification preferences for when and where run results should be posted. -- The app can be configured at the organization-level and project-level which supports multiple teams working on separate projects. +- The app can be configured at the organization-level and project-level which supports multiple teams working on separate projects. ### Per-Organization vs per-project configuration The following describes where to go to configure Slack for an organization and a project. The remaining sections will describe the supported configuration options. #### Organization settings + To share Slack configuration for an organization: + 1. Navigate to the Integrations page for the organization you wish to configure. 2. Within the Slack integration, click Configure. 3. Configure the app. #### Project settings + To share Slack configuration for a project: + 1. Navigate to the Project Settings page for the project you wish to configure. 2. Click on the Integrations tab within the Project Settings page. 3. Configure the app with the Slack Integration section. @@ -146,11 +155,13 @@ manages your information. ### Authorizations When authorized, Cypress can: - - View information about a user’s identity - - Post messages to specific channels in Slack & direct message conversations - - Show previews of cloud.cypress.io URLs in messages - - View URLs from cloud.cypress.io + +- View information about a user’s identity +- Post messages to specific channels in Slack & direct message conversations +- Show previews of cloud.cypress.io URLs in messages +- View URLs from cloud.cypress.io ### App scopes + - User token scopes: `links:read`, `links:write` - Bot token scopes: `chat:write`, `incoming-webhook`, `links:read`, `links:write` From c07b2ad8643bcd7fd71ac6f99d0f816dc5067339 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Wed, 25 Sep 2024 10:18:42 -0500 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Jennifer Shehane --- docs/guides/cloud/integrations/slack.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/guides/cloud/integrations/slack.mdx b/docs/guides/cloud/integrations/slack.mdx index 446b743b55..a44347437d 100644 --- a/docs/guides/cloud/integrations/slack.mdx +++ b/docs/guides/cloud/integrations/slack.mdx @@ -51,7 +51,7 @@ The following describes where to go to configure Slack for an organization and a #### Organization settings -To share Slack configuration for an organization: +Configure Slack for the organization: 1. Navigate to the Integrations page for the organization you wish to configure. 2. Within the Slack integration, click Configure. @@ -59,7 +59,7 @@ To share Slack configuration for an organization: #### Project settings -To share Slack configuration for a project: +Configurate Slack for a project: 1. Navigate to the Project Settings page for the project you wish to configure. 2. Click on the Integrations tab within the Project Settings page. @@ -80,15 +80,15 @@ Cypress Cloud will begin to post run results to the channel. ### Direct messages -You can have Cypress Cloud post run results to specific user. To post to a user: +You can have Cypress Cloud post run results as a direct message to a single user. To post to a direct message: 1. Navigate to the Slack configuration page 2. Click **Add Slack Channel**. 3. You'll see a popup window that allows you to choose the channel or individual associate with the organization. -4. Search for and selecting the user that messages should be sent to. +4. Search for and select the user that messages should be sent to. -Cypress Cloud will begin to send run results to the this user. +Cypress Cloud will begin to send run results to this user. ### Notification preferences @@ -121,7 +121,7 @@ and resume notifications for a specific channel without losing the configuration you've put in place. 1. Navigate to the Slack configuration page -2. Under **Actions**, select your **Mute** for each Slack channel you want +2. Under **Actions**, select **Mute** for each Slack channel you want muted. ### Remove a Slack channel @@ -131,7 +131,7 @@ remove all Slack channels if you'd prefer to disable global notifications altogether in favor of per-project notifications. 1. Navigate to the Slack configuration page -2. Under **Actions**, select your **Delete** for each Slack channel you want +2. Under **Actions**, select **Delete** for each Slack channel you want deleted. ## Remove the integration From de2a2f877a764c97354677c93e163a6eaefe3506 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Wed, 25 Sep 2024 10:22:07 -0500 Subject: [PATCH 5/5] Apply suggestions from code review --- docs/guides/cloud/integrations/slack.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/cloud/integrations/slack.mdx b/docs/guides/cloud/integrations/slack.mdx index a44347437d..a1885af0cd 100644 --- a/docs/guides/cloud/integrations/slack.mdx +++ b/docs/guides/cloud/integrations/slack.mdx @@ -163,5 +163,5 @@ When authorized, Cypress can: ### App scopes -- User token scopes: `links:read`, `links:write` -- Bot token scopes: `chat:write`, `incoming-webhook`, `links:read`, `links:write` +- User token scopes: [`links:read`](https://api.slack.com/scopes/links:read), [`links:write`](https://api.slack.com/scopes/links:write) +- Bot token scopes: [`chat:write`](https://api.slack.com/scopes/chat:write), [`incoming-webhook`](https://api.slack.com/scopes/incoming-webhook), [`links:read`](https://api.slack.com/scopes/links:read), [`links:write`](https://api.slack.com/scopes/links:write)