Project Planning and Workflow Setup Guide for Chromatic & StackShift

This guide provides step-by-step instructions for setting up a project workflow using Chromatic and the StackShift App. It covers preparing your repository, enabling visual tests, and configuring bran...

This guide provides step-by-step instructions for setting up a project workflow using Chromatic and the StackShift App. It covers preparing your repository, enabling visual tests, and configuring branch protections in GitHub to maintain high code quality throughout development.

1. Setting Up Chromatic Workflow on Your Repository

  • Create a Pull Request from the master branch to initiate the process.

  • Confirm that Chromatic workflow actions are visible under the ACTIONS tab in your GitHub repository. The Chromatic workflow can be accessed directly in the Actions list.

  • Note: The first workflow may fail if the project token isn’t set up yet. The main goal is to trigger the Chromatic workflow initially.

2. Project Setup in Chromatic

  • Add your project to the Chromatic “webriq” account to obtain the required project token. Account Name Project Token webriq 2

  • Access this token, as it will be needed for the next step.

3. Configuring StackShift Visual Tests

  • Navigate to the StackShift App Website page.

  • Go to Add-ons > Visual Tests and enable this add-on by entering your project token. Add-ons Status Dev Console ENABLED Visual Tests DISABLED AI-powered Experience ENABLED E-Commerce Experience DISABLED End to End Tests DISABLED

  • To use dev mode as an Experience, ensure you have a local setup prepared.

  • Visualize any new UI introduced by pull requests and power site suggestions with AI.

  • Enable E2E tests to confirm component and studio functionality post-deployment.

4. One-Time Add-on Setup

  • Domains and Theme Settings should be ENABLED.

  • Integrations and Builds may remain DISABLED until required.

  • Paste in your project token and submit configuration to activate the workflow.

5. How to Test UI Automatically

  • Initiate the workflow (Chromatic) by pushing commits to your pull request.

  • Use the status indicators in Chromatic (UI Review, UI Tests) to track progress.

  • Ensure that status checks have passed before proceed with merges.

6. Setting Up Branch Protection in GitHub

  • Access repository settings under the Settings tab and select Branches.

  • Click Edit for your branch protection rules—usually applied to the master branch.

  • Enable critical rules:

  • Require a pull request before merging

  • Require status checks to pass before merging

  • Require branches to be up to date before merging

  • Add required status checks (such as "UI Tests" and "UI Review") for the branch.

  • Save your changes to enforce the protection settings.

Conclusion

Following these steps ensures that your project is configured for a robust, automated workflow with visual testing, branch protections, and easy collaboration between Chromatic and StackShift. This helps maintain code integrity and accelerates your development cycles.