github.com/pyroscope-io/pyroscope@v0.37.3-0.20230725203016-5f6947968bd0/cypress/README.md (about)

     1  # Cypress tests
     2  
     3  [Cypress](https://www.cypress.io/) is a end-to-end testing library, used mainly to simulate real user scenario (ie. clicking around and interacting with).
     4  
     5  # Running locally
     6  
     7  While running the dev server, run `yarn cy:open`
     8  Which will spawn a browser, click on the file that you want to work on. It will be refreshed automatically whenever you update that file.
     9  
    10  Or run `yarn cy:ci` to run all tests.
    11  
    12  # Writing tests
    13  
    14  - Try to use [testids](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change/) to select DOM elements
    15  - Since our application is relatively simple, there's no need for Page Objects yet
    16  - [Don't write small tests with single assertions](https://docs.cypress.io/guides/references/best-practices#Creating-tiny-tests-with-a-single-assertion)
    17  - [Mock HTTP requests](https://docs.cypress.io/guides/guides/network-requests#Stub-Responses) when appropriate
    18  
    19  # Visual testing
    20  ## tl;dr
    21  To update the snapshots, run
    22  ```
    23  yarn cy:ss
    24  ```
    25  (`ss` stands for **screenshot**)
    26  
    27  It requires docker installed and available under the `docker` binary in `PATH`.
    28  (Not tested with `podman` or other alternatives)
    29  
    30  To just run without updating the snapshots, run
    31  ```
    32  yarn cy:ss-check
    33  ```
    34  
    35  ## Why
    36  Part of our core functionality revolves around rendering a flamegraph **canvas**,
    37  which is not straightforward to test.
    38  
    39  We've decided to test it using [visual testing](https://docs.cypress.io/guides/tooling/visual-testing#Functional-vs-visual-testing).
    40  
    41  ## How
    42  
    43  We use the [jaredpalmer/cypress-image-snapshot](https://github.com/jaredpalmer/cypress-image-snapshot) plugin to compare against "golden" screenshots.
    44  
    45  By default, visual testing is disabled (we instead log a `Screenshot comparison is disabled` message). That happens because comparing images is flaky, since it depends on many factors like OS, browser, viewport and pixel density, to name a few.
    46  
    47  Therefore we decided to update snapshots via a docker container, which is the same container that runs in ci. That way we have a consistent experience.
    48  
    49  If we ever update the docker image (`cypress/included:8.4.1` at the time of this writing). We need to update in 2 places (`scripts/cypress-screenshots.sh` and in `.github/workflows/cypress-tests.yml`)
    50  
    51  
    52  ## Debugging visual tests
    53  These can be very painful. We recommend recording videos (it's enabled by default), they help understand what's going on.
    54  
    55  Feel free to add any tips as you learn about them.
    56  
    57  ## References
    58  https://www.thisdot.co/blog/how-to-set-up-screenshot-comparison-testing-with-cypress-inside-an-nx
    59  https://www.youtube.com/watch?v=1XQbGtRITys&list=PLP9o9QNnQuAYhotnIDEUQNXuvXL7ZmlyZ&index=14
    60  
    61  # Updating cypress
    62  There are 3 places to update:
    63  
    64  - `package.json`
    65  - `scripts/cypress-screenshots.sh`
    66  - `.github/workflows/cypress-tests.yml`
    67  
    68  They should be ALL in sync, otherwise you gonna have weird failures, specially with snapshot tests.
    69  
    70  Don't forget to regenerate the snapshots (`yarn cy:ss`).