├── .editorconfig ├── .gitignore ├── .prettierrc ├── .ruby-version ├── .vscode └── settings.json ├── 404.html ├── Gemfile ├── Gemfile.lock ├── LICENSE.txt ├── README.md ├── _config.yml ├── _includes ├── footer.html ├── header.html ├── register-service-worker.html ├── symbols.html └── toc-tree.html ├── _layouts ├── book.html ├── chapter.html └── default.html ├── _sass ├── accessible-hide.scss ├── book-partial.scss ├── content.scss ├── dark-scheme.scss ├── fonts.scss ├── highlight.scss ├── mixins.scss ├── reset.scss └── variables.scss ├── about.md ├── acknowledgements.md ├── angular-testing-principles.md ├── assets ├── css │ └── book.scss ├── fonts │ ├── LICENSE.md │ ├── dl-noto-sans-fonts.sh │ ├── noto-sans-italic-bold-latin-ext.woff2 │ ├── noto-sans-italic-bold-latin.woff2 │ ├── noto-sans-italic-normal-latin-ext.woff2 │ ├── noto-sans-italic-normal-latin.woff2 │ ├── noto-sans-normal-bold-latin-ext.woff2 │ ├── noto-sans-normal-bold-latin.woff2 │ ├── noto-sans-normal-normal-latin-ext.woff2 │ └── noto-sans-normal-normal-latin.woff2 ├── img │ ├── README │ ├── code-coverage-flickr-search.png │ ├── code-coverage-photo-item-uncovered.png │ ├── code-coverage-photo-item.png │ ├── cypress-choose-browser.png │ ├── cypress-choose-testing-type.png │ ├── cypress-runner.png │ ├── cypress-spec-failed.png │ ├── cypress-spec.png │ ├── cypress-tests.png │ ├── favicons │ │ ├── favicon-144x144.png │ │ ├── favicon-16x16.png │ │ ├── favicon-194x194.png │ │ ├── favicon-32x32.png │ │ ├── favicon-96x96.png │ │ ├── favicon.ico │ │ └── favicon.svg │ ├── flying-probe-1200-ogimage-85.jpg │ ├── flying-probe-1344-cavif-q50.avif │ ├── flying-probe-1344-cwebp-q80.webp │ ├── flying-probe-1344-q65.jpg │ ├── flying-probe-2-1-2085-cwebp-q80.webp │ ├── flying-probe-672-cavif-q60.avif │ ├── flying-probe-672-cwebp-q80.webp │ ├── flying-probe-672-q85.jpg │ ├── jasmine-debug-runner.png │ ├── jasmine-debugger.png │ ├── jasmine-dom.png │ ├── karma-jasmine-html-reporter.png │ ├── karma-select-context.png │ └── karma-success.png ├── js │ ├── collapse-toc.js │ ├── highlight-toc.js │ └── iframe-buttons.js └── testing-angular.epub ├── debugging-tests.md ├── end-to-end-testing.md ├── example-applications.md ├── faking-dependencies.md ├── index-of-example-applications.md ├── index.html ├── introduction.md ├── license.md ├── localhost.crt ├── localhost.key ├── measuring-code-coverage.md ├── offline.html ├── references.md ├── robots.txt ├── service-worker.js ├── summary.md ├── target-audience.md ├── terminology.md ├── test-suites-with-jasmine.md ├── testing-complex-forms.md ├── testing-components-depending-on-services.md ├── testing-components-with-children.md ├── testing-components-with-spectator.md ├── testing-components.md ├── testing-directives.md ├── testing-modules.md ├── testing-pipes.md ├── testing-principles.md └── testing-services.md /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | end_of_line = lf 5 | insert_final_newline = true 6 | charset = utf-8 7 | indent_style = space 8 | indent_size = 2 9 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | _site 2 | .sass-cache 3 | .jekyll-cache 4 | .jekyll-metadata 5 | vendor 6 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "singleQuote": true 3 | } -------------------------------------------------------------------------------- /.ruby-version: -------------------------------------------------------------------------------- 1 | 3.3.0 2 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "editor.formatOnSave": false 3 | } 4 | -------------------------------------------------------------------------------- /404.html: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /404.html 3 | layout: default 4 | --- 5 | 6 | 19 | 20 |
21 |

404

22 | 23 |

Page not found :(

24 |

The requested page could not be found.

25 |
26 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | 3 | gem "jekyll" 4 | 5 | # Do not use a jekyll_plugins group so the _config.yml controls which plugins are loaded 6 | # See https://jekyllrb.com/docs/plugins/installation/ 7 | gem "jekyll-last-modified-at" 8 | gem "jekyll-brotli" 9 | gem "jekyll-minifier" 10 | 11 | gem "webrick" 12 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | addressable (2.8.6) 5 | public_suffix (>= 2.0.2, < 6.0) 6 | brotli (0.2.3) 7 | colorator (1.1.0) 8 | concurrent-ruby (1.2.3) 9 | cssminify2 (2.0.1) 10 | em-websocket (0.5.3) 11 | eventmachine (>= 0.12.9) 12 | http_parser.rb (~> 0) 13 | eventmachine (1.2.7) 14 | execjs (2.9.1) 15 | ffi (1.16.3) 16 | forwardable-extended (2.6.0) 17 | google-protobuf (4.26.1) 18 | rake (>= 13) 19 | google-protobuf (4.26.1-aarch64-linux) 20 | rake (>= 13) 21 | google-protobuf (4.26.1-arm64-darwin) 22 | rake (>= 13) 23 | google-protobuf (4.26.1-x86-linux) 24 | rake (>= 13) 25 | google-protobuf (4.26.1-x86_64-darwin) 26 | rake (>= 13) 27 | google-protobuf (4.26.1-x86_64-linux) 28 | rake (>= 13) 29 | htmlcompressor (0.4.0) 30 | http_parser.rb (0.8.0) 31 | i18n (1.14.4) 32 | concurrent-ruby (~> 1.0) 33 | jekyll (4.3.3) 34 | addressable (~> 2.4) 35 | colorator (~> 1.0) 36 | em-websocket (~> 0.5) 37 | i18n (~> 1.0) 38 | jekyll-sass-converter (>= 2.0, < 4.0) 39 | jekyll-watch (~> 2.0) 40 | kramdown (~> 2.3, >= 2.3.1) 41 | kramdown-parser-gfm (~> 1.0) 42 | liquid (~> 4.0) 43 | mercenary (>= 0.3.6, < 0.5) 44 | pathutil (~> 0.9) 45 | rouge (>= 3.0, < 5.0) 46 | safe_yaml (~> 1.0) 47 | terminal-table (>= 1.8, < 4.0) 48 | webrick (~> 1.7) 49 | jekyll-brotli (2.4.0) 50 | brotli (~> 0.2.0) 51 | jekyll (>= 3.0, < 5.0) 52 | jekyll-last-modified-at (1.3.0) 53 | jekyll (>= 3.7, < 5.0) 54 | posix-spawn (~> 0.3.9) 55 | jekyll-minifier (0.1.10) 56 | cssminify2 (~> 2.0) 57 | htmlcompressor (~> 0.4) 58 | jekyll (>= 3.5) 59 | json-minify (~> 0.0.3) 60 | uglifier (~> 4.1) 61 | jekyll-sass-converter (3.0.0) 62 | sass-embedded (~> 1.54) 63 | jekyll-watch (2.2.1) 64 | listen (~> 3.0) 65 | json (2.7.1) 66 | json-minify (0.0.3) 67 | json (> 0) 68 | kramdown (2.4.0) 69 | rexml 70 | kramdown-parser-gfm (1.1.0) 71 | kramdown (~> 2.0) 72 | liquid (4.0.4) 73 | listen (3.9.0) 74 | rb-fsevent (~> 0.10, >= 0.10.3) 75 | rb-inotify (~> 0.9, >= 0.9.10) 76 | mercenary (0.4.0) 77 | pathutil (0.16.2) 78 | forwardable-extended (~> 2.6) 79 | posix-spawn (0.3.15) 80 | public_suffix (5.0.4) 81 | rake (13.1.0) 82 | rb-fsevent (0.11.2) 83 | rb-inotify (0.10.1) 84 | ffi (~> 1.0) 85 | rexml (3.2.6) 86 | rouge (4.2.1) 87 | safe_yaml (1.0.5) 88 | sass-embedded (1.72.0) 89 | google-protobuf (>= 3.25, < 5.0) 90 | rake (>= 13.0.0) 91 | sass-embedded (1.72.0-aarch64-linux-android) 92 | google-protobuf (>= 3.25, < 5.0) 93 | sass-embedded (1.72.0-aarch64-linux-gnu) 94 | google-protobuf (>= 3.25, < 5.0) 95 | sass-embedded (1.72.0-aarch64-linux-musl) 96 | google-protobuf (>= 3.25, < 5.0) 97 | sass-embedded (1.72.0-arm-linux-androideabi) 98 | google-protobuf (>= 3.25, < 5.0) 99 | sass-embedded (1.72.0-arm-linux-gnueabihf) 100 | google-protobuf (>= 3.25, < 5.0) 101 | sass-embedded (1.72.0-arm-linux-musleabihf) 102 | google-protobuf (>= 3.25, < 5.0) 103 | sass-embedded (1.72.0-arm64-darwin) 104 | google-protobuf (>= 3.25, < 5.0) 105 | sass-embedded (1.72.0-x86-linux-android) 106 | google-protobuf (>= 3.25, < 5.0) 107 | sass-embedded (1.72.0-x86-linux-gnu) 108 | google-protobuf (>= 3.25, < 5.0) 109 | sass-embedded (1.72.0-x86-linux-musl) 110 | google-protobuf (>= 3.25, < 5.0) 111 | sass-embedded (1.72.0-x86_64-darwin) 112 | google-protobuf (>= 3.25, < 5.0) 113 | sass-embedded (1.72.0-x86_64-linux-android) 114 | google-protobuf (>= 3.25, < 5.0) 115 | sass-embedded (1.72.0-x86_64-linux-gnu) 116 | google-protobuf (>= 3.25, < 5.0) 117 | sass-embedded (1.72.0-x86_64-linux-musl) 118 | google-protobuf (>= 3.25, < 5.0) 119 | terminal-table (3.0.2) 120 | unicode-display_width (>= 1.1.1, < 3) 121 | uglifier (4.2.0) 122 | execjs (>= 0.3.0, < 3) 123 | unicode-display_width (2.5.0) 124 | webrick (1.8.1) 125 | 126 | PLATFORMS 127 | aarch64-linux 128 | aarch64-linux-android 129 | aarch64-linux-gnu 130 | aarch64-linux-musl 131 | arm-linux-androideabi 132 | arm-linux-gnueabihf 133 | arm-linux-musleabihf 134 | arm64-darwin 135 | ruby 136 | x86-linux 137 | x86-linux-android 138 | x86-linux-gnu 139 | x86-linux-musl 140 | x86_64-darwin 141 | x86_64-linux 142 | x86_64-linux-android 143 | x86_64-linux-gnu 144 | x86_64-linux-musl 145 | 146 | DEPENDENCIES 147 | jekyll 148 | jekyll-brotli 149 | jekyll-last-modified-at 150 | jekyll-minifier 151 | webrick 152 | 153 | BUNDLED WITH 154 | 2.5.7 155 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) 2 | 3 | You are free to: 4 | 5 | Share — copy and redistribute the material in any medium or format 6 | Adapt — remix, transform, and build upon the material for any purpose, even commercially. 7 | 8 | https://creativecommons.org/licenses/by-sa/4.0/ 9 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # [Testing Angular – A Guide to Robust Angular Applications](https://testing-angular.com/) 2 | 3 | A free online book and e-book. [Read the book online](https://testing-angular.com/). 4 | 5 | [Download the book as EPUB (1.8 MB)](https://testing-angular.com/assets/testing-angular.epub) 6 | 7 | # Feedback 8 | 9 | Please send feedback and corrections to molily@mailbox.org or [file an issue on GitHub](https://github.com/molily/testing-angular/issues/new). Thanks! 10 | 11 | # Example Applications 12 | 13 | All example applications are repositories on GitHub: 14 | 15 | - [Counter Component](https://github.com/9elements/angular-workshop) 16 | - [Flickr photo search](https://github.com/9elements/angular-flickr-search) 17 | - [Sign-up form](https://github.com/molily/angular-form-testing) 18 | - [TranslatePipe](https://github.com/molily/translate-pipe) 19 | - [ThresholdWarningDirective](https://github.com/molily/threshold-warning-directive) 20 | - [PaginateDirective](https://github.com/molily/paginate-directive) 21 | 22 | # License 23 | 24 | License: [Creative Commons Attribution-ShareAlike (CC BY-SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/) 25 | 26 | The example code is released into the public domain. See [Unlicense](https://unlicense.org/). 27 | 28 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | # Site settings 2 | title: Testing Angular 3 | subtitle: A Guide to Robust Angular Applications 4 | email: molily@mailbox.org 5 | description: "Unit, integration and end-to-end tests for Angular web applications. Free online book and e-book." 6 | keywords: JavaScript, Angular, testing, automated tests, test automation, unit tests, integration tests, end-to-end tests 7 | twitter_card: summary_large_image 8 | twitter_image: /assets/img/flying-probe-2-1-2085-cwebp-q80.webp 9 | og_image: /assets/img/flying-probe-1200-ogimage-85.jpg 10 | baseurl: "" # the subpath of your site, e.g. /blog/ 11 | url: "https://testing-angular.com" 12 | permalink: /:title/ 13 | 14 | # Build settings 15 | host: 0.0.0.0 16 | markdown: kramdown 17 | 18 | sass: 19 | style: compressed 20 | 21 | plugins: 22 | - jekyll-last-modified-at 23 | - jekyll-brotli 24 | - jekyll-minifier 25 | 26 | # Optional. The default date format, used if none is specified in the tag. 27 | last-modified-at: 28 | date-format: '%Y-%m-%d' 29 | 30 | jekyll-minifier: 31 | exclude: 'service-worker.js' 32 | -------------------------------------------------------------------------------- /_includes/footer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 27 | 28 | 29 | -------------------------------------------------------------------------------- /_includes/header.html: -------------------------------------------------------------------------------- 1 | {% include symbols.html %} 2 | 3 |

Skip navigation, jump to main content

4 | 5 | 11 | 12 | 29 | 30 |
31 |
32 | -------------------------------------------------------------------------------- /_includes/register-service-worker.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /_includes/symbols.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | -------------------------------------------------------------------------------- /_includes/toc-tree.html: -------------------------------------------------------------------------------- 1 |
    2 |
  1. Introduction
    2. 3 |
  2. Target audience
    3. 4 |
  3. Terminology
    4. 5 |
  4. 6 | Testing principles 7 |
      8 |
    1. What makes a good test
      2. 9 |
    2. 10 | What testing can achieve 11 |
      3. 12 |
    3. 13 | Tailoring your testing approach 14 |
      4. 15 |
    4. 16 | The right amount of testing 17 |
      5. 18 |
    5. 19 | Levels of testing 20 |
        21 |
      1. End-to-end tests
        2. 22 |
      2. Unit tests
        3. 23 |
      3. Integration tests
        4. 24 |
      25 |
      6. 26 |
    6. 27 | Distribution of testing efforts 28 |
      7. 29 |
    7. 30 | Black box vs. white box testing 31 |
      8. 32 |
    33 |
    5. 34 |
  5. 35 | Example applications 36 |
      37 |
    1. The counter Component
      2. 38 |
    2. 39 | The Flickr photo search 40 |
      3. 41 |
    42 |
    6. 43 |
  6. 44 | Angular testing principles 45 |
      46 |
    1. Testability
      2. 47 |
    2. 48 | Dependency injection and faking 49 |
      3. 50 |
    3. Testing tools
      4. 51 |
    4. Testing conventions
      5. 52 |
    5. 53 | Running the unit and integration tests 54 |
      6. 55 |
    6. 56 | Configuring Karma and Jasmine 57 |
      7. 58 |
    59 |
    7. 60 |
  7. 61 | Test suites with Jasmine 62 |
      63 |
    1. Creating a test suite
      2. 64 |
    2. Specifications
      3. 65 |
    3. Structure of a test
      4. 66 |
    4. Expectations
      5. 67 |
    5. Efficient test suites
      6. 68 |
    69 |
    8. 70 |
  8. 71 | Faking dependencies 72 |
      73 |
    1. 74 | Equivalence of fake and original 75 |
      2. 76 |
    2. Effective faking
      3. 77 |
    3. 78 | Faking functions with Jasmine spies 79 |
      4. 80 |
    4. 81 | Spying on existing methods 82 |
      5. 83 |
    84 |
    9. 85 |
  9. 86 | Debugging tests 87 |
      88 |
    1. Test focus
      2. 89 |
    2. Developer tools
      3. 90 |
    3. 91 | Debug output and the JavaScript debugger 92 |
      4. 93 |
    4. Inspect the DOM
      5. 94 |
    5. Jasmine debug runner
      6. 95 |
    96 |
    10. 97 |
  10. 98 | Testing Components 99 |
      100 |
    1. 101 | Unit test for the counter Component 102 |
      2. 103 |
    2. TestBed
      3. 104 |
    3. 105 | Configuring the testing Module 106 |
      4. 107 |
    4. 108 | Rendering the Component 109 |
      5. 110 |
    5. TestBed and Jasmine
      6. 111 |
    6. 112 | ComponentFixture and DebugElement 113 |
      7. 114 |
    7. 115 | Writing the first Component spec 116 |
      8. 117 |
    8. 118 | Querying the DOM with test ids 119 |
      9. 120 |
    9. 121 | Triggering event handlers 122 |
      10. 123 |
    10. Expecting text output
      11. 124 |
    11. Testing helpers
      12. 125 |
    12. Filling out forms
      13. 126 |
    13. Testing Inputs
      14. 127 |
    14. Testing Outputs
      15. 128 |
    15. 129 | Repetitive Component specs 130 |
      16. 131 |
    16. 132 | Black vs. white box Component testing 133 |
      17. 134 |
    135 |
    11. 136 |
  11. 137 | Testing Components with children 138 |
      139 |
    1. 140 | Shallow vs. deep rendering 141 |
      2. 142 |
    2. 143 | Unit test 144 |
      3. 145 |
    3. 146 | Faking a child Component 147 |
      4. 148 |
    4. 149 | Faking a child Component with ng-mocks 150 |
      5. 151 |
    152 |
    12. 153 |
  12. 154 | Testing Components depending on Services 155 |
      156 |
    1. 157 | Service dependency integration test 158 |
      2. 159 |
    2. 160 | Faking Service dependencies 161 |
      3. 162 |
    3. 163 | Fake Service with minimal logic 164 |
      4. 165 |
    4. 166 | Faking Services: Summary 167 |
      5. 168 |
    169 |
    13. 170 |
  13. 171 | Testing complex forms 172 |
      173 |
    1. Sign-up form Component
      2. 174 |
    2. 175 | Form validation and errors 176 |
      3. 177 |
    3. Test plan
      4. 178 |
    4. Test setup
      5. 179 |
    5. 180 | Successful form submission 181 |
      6. 182 |
    6. Invalid form
      7. 183 |
    7. 184 | Form submission failure 185 |
      8. 186 |
    8. Required fields
      9. 187 |
    9. 188 | Asynchronous validators 189 |
      10. 190 |
    10. 191 | Dynamic field relations 192 |
      11. 193 |
    11. Password type toggle
      12. 194 |
    12. 195 | Testing form accessibility 196 |
        197 |
      1. pa11y
        2. 198 |
      2. pa11y-ci
        3. 199 |
      3. 200 | Start server and run pa11y-ci 201 |
        4. 202 |
      203 |
      13. 204 |
    13. 205 | Form accessibility: Summary 206 |
      14. 207 |
    208 |
    14. 209 |
  14. 210 | Testing Components with Spectator 211 |
      212 |
    1. 213 | Component with an Input 214 |
      2. 215 |
    2. 216 | Component with children and Service dependency 217 |
      3. 218 |
    3. 219 | Event handling with Spectator 220 |
      4. 221 |
    4. Spectator: Summary
      5. 222 |
    223 |
    15. 224 |
  15. 225 | Testing Services 226 |
      227 |
    1. 228 | Testing a Service with internal state 229 |
      2. 230 |
    2. 231 | Testing a Service that sends HTTP requests 232 |
        233 |
      1. 234 | Call the method under test 235 |
        2. 236 |
      2. 237 | Find pending requests 238 |
        3. 239 |
      3. 240 | Respond with fake data 241 |
        4. 242 |
      4. 243 | Check the result of the method call 244 |
        5. 245 |
      5. 246 | Verify that all requests have been answered 247 |
        6. 248 |
      6. 249 | Testing the error case 250 |
        7. 251 |
      7. 252 | Alternatives for finding pending requests 253 |
        8. 254 |
      255 |
      3. 256 |
    3. 257 | Testing Services: Summary 258 |
      4. 259 |
    260 |
    16. 261 |
  16. 262 | Testing Pipes 263 |
      264 |
    1. GreetPipe
      2. 265 |
    2. GreetPipe test
      3. 266 |
    3. 267 | Testing Pipes with dependencies 268 |
        269 |
      1. TranslateService
        2. 270 |
      2. TranslatePipe
        3. 271 |
      3. TranslatePipe test
        4. 272 |
      273 |
      4. 274 |
    275 |
    17. 276 |
  17. 277 | Testing Directives 278 |
      279 |
    1. 280 | Testing Attribute Directives 281 |
        282 |
      1. 283 | ThresholdWarningDirective 284 |
        2. 285 |
      2. 286 | ThresholdWarningDirective test 287 |
        3. 288 |
      289 |
      2. 290 |
    2. 291 | Testing Structural Directives 292 |
        293 |
      1. PaginateDirective
        2. 294 |
      2. 295 | PaginateDirective test 296 |
        3. 297 |
      298 |
      3. 299 |
    300 |
    18. 301 |
  18. Testing Modules
    19. 302 |
  19. 303 | Measuring code coverage 304 |
      305 |
    1. Coverage report
      2. 306 |
    2. 307 | How to use the coverage report 308 |
      3. 309 |
    310 |
    20. 311 |
  20. 312 | End-to-end testing 313 |
      314 |
    1. 315 | Strengths of end-to-end tests 316 |
      2. 317 |
    2. 318 | Deployment for end-to-end tests 319 |
      3. 320 |
    3. 321 | How end-to-end tests work 322 |
      4. 323 |
    4. 324 | End-to-end testing frameworks 325 |
      5. 326 |
    5. Introducing Cypress
      6. 327 |
    6. Installing Cypress
      7. 328 |
    7. 329 | Writing an end-to-end test with Cypress 330 |
      8. 331 |
    8. 332 | Testing the counter Component 333 |
      9. 334 |
    9. 335 | Running the Cypress tests 336 |
      10. 337 |
    10. Asynchronous tests
      11. 338 |
    11. 339 | Automatic retries and waiting 340 |
      12. 341 |
    12. 342 | Testing the counter increment 343 |
      13. 344 |
    13. Finding elements
      14. 345 |
    14. 346 | Interacting with elements 347 |
      15. 348 |
    15. 349 | Custom Cypress commands 350 |
      16. 351 |
    16. 352 | Testing the Flickr search 353 |
        354 |
      1. 355 | Testing the search form 356 |
        2. 357 |
      2. 358 | Testing the full photo 359 |
        3. 360 |
      361 |
      17. 362 |
    17. Page objects
      18. 363 |
    18. Faking the Flickr API
      19. 364 |
    19. 365 | End-to-end testing: Summary 366 |
      20. 367 |
    368 |
    21. 369 |
  21. Summary
    22. 370 |
  22. 371 | Index of example applications 372 |
    23. 373 |
  23. References
    24. 374 |
  24. Acknowledgements
    25. 375 |
  25. About
    26. 376 |
  26. License
    27. 377 |
378 | -------------------------------------------------------------------------------- /_layouts/book.html: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | {% capture title %} 5 | {% if page.title %} 6 | {{ page.title }}{% if page.append_site_title != false %} – {{ site.title }}{% endif %} 7 | {% else %} 8 | {{ site.title }} 9 | {% endif %} 10 | {% endcapture %} 11 | 12 | {{ title | strip | strip_newlines }} 13 | 14 | 15 | 16 | {% capture canonical_url %}{{ page.url | replace:'index.html','' | prepend: site.baseurl | prepend: site.url }}{% endcapture %} 17 | 18 | {% capture description %} 19 | {% if page.description %} 20 | {{ page.description }} 21 | {% else %} 22 | {{ site.description }} 23 | {% endif %} 24 | {% endcapture %} 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | {% if page.robots %} 66 | 67 | {% endif %} 68 | 69 | 70 | 71 | 72 | {{ content }} 73 | 74 | {% include register-service-worker.html %} 75 | 76 | -------------------------------------------------------------------------------- /_layouts/chapter.html: -------------------------------------------------------------------------------- 1 | --- 2 | layout: book 3 | --- 4 | 5 | {% include header.html %} 6 | 7 | {{ content }} 8 | 9 | {% include footer.html %} 10 | -------------------------------------------------------------------------------- /_layouts/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | {{ content }} 6 | 7 | 8 | -------------------------------------------------------------------------------- /_sass/accessible-hide.scss: -------------------------------------------------------------------------------- 1 | // Hide and show content accessibly. The content is visually hidden, but 2 | // screen readers and other assistive technology should still read it. 3 | // http://snook.ca/archives/html_and_css/hiding-content-for-accessibility 4 | @mixin accessible-hide { 5 | position: absolute; 6 | // Without any top/right/bottom/left declaration, the element would be 7 | // positioned at its position in the normal flow. This may cause scrollbars 8 | // so we move it to top/left position of the containing block. 9 | left: 0; 10 | top: 0; 11 | height: 1px; 12 | width: 1px; 13 | overflow: hidden; 14 | // Legacy syntax for IE6 and IE7 15 | clip: rect(1px 1px 1px 1px); 16 | clip: rect(1px, 1px, 1px, 1px); 17 | } 18 | 19 | @mixin accessible-show { 20 | position: static; 21 | height: auto; 22 | width: auto; 23 | overflow: visible; 24 | clip: auto; 25 | } 26 | 27 | %accessible-hide { 28 | @include accessible-hide; 29 | } 30 | 31 | %accessible-show { 32 | @include accessible-hide; 33 | } 34 | -------------------------------------------------------------------------------- /_sass/book-partial.scss: -------------------------------------------------------------------------------- 1 | @use 'sass:math'; 2 | 3 | /** 4 | * Book styles 5 | */ 6 | 7 | @import 'reset'; 8 | @import 'fonts'; 9 | @import 'mixins'; 10 | @import 'content'; 11 | @import 'highlight'; 12 | 13 | /** 14 | * @section Variables 15 | */ 16 | 17 | $toc-width: 25rem; 18 | $main-max-width: 42rem; 19 | 20 | $angular-primary-color: #1976d2; 21 | 22 | $toc-background: #f9f9f9; 23 | $toc-background-inverted: $dark-background-color-inverted; 24 | 25 | $sticky-menu-background: #f0f0f0; 26 | $sticky-menu-background-inverted: $dark-background-color-inverted; 27 | 28 | $dark-highlight-background-color: adjust-color( 29 | $highlight-background-color, 30 | $lightness: -2% 31 | ); 32 | $dark-highlight-background-color-inverted: adjust-color( 33 | $highlight-background-color, 34 | $lightness: -2% 35 | ); 36 | 37 | $font-size-small: math.percentage(math.div(16, 18)); 38 | $font-size-smallest: math.percentage(math.div(15, 18)); 39 | 40 | /** 41 | * @section Root element and Body 42 | */ 43 | 44 | html { 45 | @include dark-scheme { 46 | background-color: $medium-background-color-inverted; 47 | } 48 | } 49 | 50 | body { 51 | padding: 1rem; 52 | 53 | @include large { 54 | padding: 0; 55 | } 56 | } 57 | 58 | /** 59 | * @section Tables 60 | */ 61 | 62 | table { 63 | // Do not use rem, use unit relative to parent font-size 64 | font-size: $font-size-small; 65 | margin-left: auto; 66 | margin-right: auto; 67 | } 68 | 69 | caption { 70 | text-align: center; 71 | } 72 | 73 | th, 74 | td { 75 | border-style: none none solid; 76 | } 77 | 78 | th { 79 | font-weight: bold; 80 | } 81 | 82 | .wide-table-wrapper { 83 | margin-left: -1rem; 84 | margin-right: -1rem; 85 | overflow: auto; 86 | } 87 | 88 | .wide-table { 89 | font-size: $font-size-small; 90 | } 91 | 92 | /** 93 | * @section Code 94 | */ 95 | 96 | pre { 97 | border-radius: 0.5px; 98 | margin-left: -1rem; 99 | margin-right: -1rem; 100 | font-size: $font-size-small; 101 | 102 | @include large { 103 | margin-left: -2rem; 104 | margin-right: -2rem; 105 | padding-left: 2rem; 106 | padding-right: 2rem; 107 | } 108 | } 109 | 110 | /** 111 | * @section Base layout 112 | */ 113 | 114 | @include large { 115 | #sidebar { 116 | position: fixed; 117 | left: 0; 118 | top: 0; 119 | bottom: 0; 120 | width: $toc-width; 121 | overflow: auto; 122 | resize: horizontal; 123 | background-color: $toc-background; 124 | 125 | @include dark-scheme { 126 | background-color: $toc-background-inverted; 127 | } 128 | } 129 | 130 | #main-container { 131 | margin-left: $toc-width; 132 | padding: 0 2rem; 133 | } 134 | } 135 | 136 | /** 137 | * @section Sticky menu 138 | */ 139 | 140 | #sticky-menu { 141 | position: sticky; 142 | top: 0; 143 | left: 0; 144 | right: 0; 145 | display: flex; 146 | justify-content: space-evenly; 147 | margin: -2rem -1rem 1rem; 148 | border-bottom: 1px solid 149 | adjust-color($sticky-menu-background, $lightness: -2%); 150 | background-color: $sticky-menu-background; 151 | font-size: $font-size-small; 152 | text-align: center; 153 | 154 | @include large { 155 | display: none; 156 | } 157 | 158 | @include dark-scheme { 159 | border-bottom: 0; 160 | background-color: $sticky-menu-background-inverted; 161 | } 162 | 163 | a:link { 164 | flex: 1; 165 | display: flex; 166 | align-items: center; 167 | justify-content: center; 168 | border: 0; 169 | padding: 0.25rem 0.5rem; 170 | text-decoration: none; 171 | line-height: 1.5; 172 | } 173 | } 174 | 175 | /** 176 | * Scroll margins 177 | */ 178 | 179 | [id] { 180 | scroll-margin-top: 4rem; 181 | } 182 | 183 | /** 184 | * @section Skip navigation links 185 | */ 186 | 187 | .skip-navigation { 188 | @include accessible-hide; 189 | 190 | &:link { 191 | text-decoration: none; 192 | transition: none; 193 | } 194 | 195 | // Make visible on focus 196 | &:focus { 197 | @include accessible-show; 198 | position: absolute; 199 | top: 0; 200 | left: 50%; 201 | z-index: 1; 202 | transform: translateX(-50%); 203 | background-color: white; 204 | padding: 0.5rem 1rem; 205 | outline-offset: 0; 206 | 207 | @include dark-scheme { 208 | background-color: $highlight-background-color-inverted; 209 | } 210 | } 211 | } 212 | 213 | /** 214 | * @section Table of contents 215 | */ 216 | 217 | #toc { 218 | @include large { 219 | padding: 2rem; 220 | } 221 | } 222 | 223 | #home-link { 224 | display: none; 225 | font-size: 0.9rem; 226 | 227 | @include large { 228 | display: flex; 229 | justify-content: space-evenly; 230 | } 231 | 232 | a { 233 | flex: 1; 234 | display: flex; 235 | align-items: center; 236 | justify-content: center; 237 | text-decoration: none; 238 | } 239 | } 240 | 241 | #toc-book-title, 242 | #toc-heading { 243 | margin: 2rem 0; 244 | } 245 | 246 | #toc-book-title { 247 | font-size: 2rem; 248 | line-height: 1.6; 249 | text-align: center; 250 | text-wrap: balance; 251 | color: $heading-color; 252 | 253 | @include large { 254 | font-size: 1.8rem; 255 | } 256 | 257 | @include dark-scheme { 258 | color: inherit; 259 | } 260 | 261 | small { 262 | display: block; 263 | } 264 | } 265 | 266 | #toc-heading { 267 | font-size: 1.2rem; 268 | text-align: center; 269 | 270 | @include large { 271 | @include accessible-hide; 272 | } 273 | 274 | @include dark-scheme { 275 | color: inherit; 276 | } 277 | } 278 | 279 | #toc-epub-link { 280 | margin-bottom: 2rem; 281 | 282 | a { 283 | display: block; 284 | padding: 0.5rem; 285 | text-align: center; 286 | text-decoration: none; 287 | background-color: $highlight-background-color; 288 | 289 | @include dark-scheme { 290 | background-color: $highlight-background-color-inverted; 291 | } 292 | } 293 | } 294 | 295 | #toc-tree { 296 | ol { 297 | margin: 0.5rem 0; 298 | font-size: $font-size-small; 299 | } 300 | 301 | .collapsed { 302 | display: none; 303 | } 304 | 305 | li { 306 | margin-bottom: 0.5rem; 307 | } 308 | 309 | li li { 310 | margin-bottom: 0; 311 | list-style-type: none; 312 | } 313 | 314 | $a-padding-left: 0.5rem; 315 | 316 | a { 317 | padding: 0 1rem 0 $a-padding-left; 318 | } 319 | 320 | // ol a {} 321 | 322 | ol ol a { 323 | padding-left: $a-padding-left + 1rem; 324 | } 325 | 326 | a { 327 | display: block; 328 | text-decoration: none; 329 | 330 | &:hover { 331 | background-color: $dark-highlight-background-color; 332 | color: $link-color; 333 | 334 | @include dark-scheme { 335 | background-color: $highlight-background-color-inverted; 336 | color: $link-color-inverted; 337 | } 338 | } 339 | } 340 | 341 | a.active { 342 | color: $toc-background; 343 | background-color: $link-color; 344 | 345 | @include dark-scheme { 346 | color: $toc-background-inverted; 347 | background-color: $link-color-inverted; 348 | } 349 | } 350 | } 351 | 352 | #cover-toc-tree { 353 | ol ol { 354 | display: none; 355 | } 356 | } 357 | 358 | #sidebar-toc-tree { 359 | @include large { 360 | margin: 0 -2rem; 361 | } 362 | } 363 | 364 | /** 365 | * @section Main 366 | */ 367 | 368 | #main { 369 | overflow-wrap: break-word; 370 | 371 | @include medium { 372 | // Slightly larger font size than the default 373 | font-size: math.div(18, 16) * 1rem; 374 | letter-spacing: 0.2px; 375 | word-spacing: 0.2px; 376 | } 377 | 378 | @include large { 379 | margin: auto; 380 | max-width: $main-max-width; 381 | } 382 | 383 | h1, 384 | h2, 385 | h3, 386 | h4, 387 | h5, 388 | h6 { 389 | margin: 4rem 0 1rem; 390 | 391 | @include dark-scheme { 392 | margin-left: -1rem; 393 | margin-right: -1rem; 394 | padding: 2rem 1rem; 395 | background-color: $highlight-background-color-inverted; 396 | border-radius: 0.5px; 397 | 398 | @include large { 399 | margin-left: -2rem; 400 | margin-right: -2rem; 401 | padding-left: 2rem; 402 | padding-right: 2rem; 403 | } 404 | } 405 | } 406 | 407 | // Use percent for heading font-size instead of rem 408 | // since #main has its own font-size 409 | 410 | h1 { 411 | margin-bottom: 2rem; 412 | font-size: 180%; 413 | } 414 | 415 | h2 { 416 | font-size: 160%; 417 | } 418 | 419 | h3 { 420 | font-size: 150%; 421 | } 422 | 423 | h4 { 424 | font-size: 140%; 425 | } 426 | } 427 | 428 | /** 429 | * Footer 430 | */ 431 | 432 | #page-footer { 433 | font-size: $font-size-small; 434 | 435 | p { 436 | margin-bottom: 1rem; 437 | } 438 | 439 | @include large { 440 | display: flex; 441 | justify-content: center; 442 | } 443 | } 444 | 445 | #page-footer-inner { 446 | @include large { 447 | max-width: $main-max-width; 448 | } 449 | } 450 | 451 | /** 452 | * @section Cover image 453 | */ 454 | 455 | #cover-image { 456 | margin: 0 0 2rem; 457 | text-align: center; 458 | font-size: $font-size-small; 459 | } 460 | 461 | /* Placeholder with the right aspect ratio 462 | to prevent layout shifts */ 463 | #cover-image-flying-probe-container { 464 | position: relative; 465 | display: block; 466 | margin: auto; 467 | padding-top: math.percentage(math.div(504, 800)); 468 | max-width: 800px; 469 | } 470 | 471 | #cover-image-flying-probe { 472 | position: absolute; 473 | top: 0; 474 | left: 0; 475 | display: block; 476 | width: 100%; 477 | height: 100%; 478 | } 479 | 480 | @supports (aspect-ratio: 800 / 504) { 481 | #cover-image-flying-probe-container { 482 | padding-top: 0; 483 | aspect-ratio: 800 / 504; 484 | } 485 | } 486 | 487 | /** 488 | * @section Cover heading 489 | */ 490 | 491 | // Boost specificity to override #main h1 492 | h1#cover-heading { 493 | margin: 3rem 0; 494 | font-size: 2.5rem; 495 | text-align: center; 496 | text-wrap: balance; 497 | 498 | @include dark-scheme { 499 | color: inherit; 500 | } 501 | 502 | @include large { 503 | margin: 4rem 0; 504 | font-size: 4rem; 505 | } 506 | 507 | br { 508 | display: none; 509 | } 510 | 511 | .cover-title, 512 | .subheading, 513 | .subheading-small { 514 | display: block; 515 | margin-bottom: 2rem; 516 | } 517 | 518 | .subheading { 519 | font-size: 1.5rem; 520 | 521 | @include large { 522 | font-size: 2.5rem; 523 | } 524 | } 525 | 526 | .subheading-small { 527 | margin-bottom: 0; 528 | font-size: 1.3rem; 529 | } 530 | } 531 | 532 | /** 533 | * Introduction 534 | */ 535 | 536 | .intro { 537 | font-size: 1.2rem; 538 | 539 | @include large { 540 | font-size: 1.25rem; 541 | } 542 | } 543 | 544 | .intro-caps { 545 | font-style: normal; 546 | font-variant: small-caps; 547 | text-transform: capitalize; 548 | } 549 | 550 | /** 551 | * @section Erroneous code 552 | */ 553 | 554 | .erroneous { 555 | pre { 556 | @include dark-scheme { 557 | background-color: adjust-color( 558 | $highlight-background-color-inverted, 559 | $red: 15 560 | ); 561 | } 562 | } 563 | } 564 | 565 | /** 566 | * @section Typographic separator 567 | */ 568 | 569 | .separator { 570 | display: block; 571 | margin: 4.5rem auto; 572 | width: 3rem; 573 | height: 3rem; 574 | color: #e0e0e0; 575 | } 576 | 577 | /** 578 | * @section Learning objectives 579 | */ 580 | 581 | .learning-objectives { 582 | margin: 0 -1rem 2rem; 583 | border-radius: 0.5px; 584 | padding: 1rem; 585 | font-size: $font-size-small; 586 | background-color: $highlight-background-color; 587 | 588 | @include large { 589 | margin-left: -2rem; 590 | margin-right: -2rem; 591 | padding-left: 2rem; 592 | padding-right: 2rem; 593 | } 594 | 595 | @include dark-scheme { 596 | background-color: $highlight-background-color-inverted; 597 | } 598 | 599 | p { 600 | margin-left: 1rem; 601 | text-transform: uppercase; 602 | letter-spacing: 0.5px; 603 | word-spacing: 1px; 604 | page-break-after: avoid; 605 | color: $heading-color; 606 | 607 | @include dark-scheme { 608 | color: $heading-color-inverted; 609 | } 610 | } 611 | 612 | ul { 613 | margin-bottom: 0; 614 | list-style-type: square; 615 | } 616 | 617 | li { 618 | margin-bottom: 0.5rem; 619 | 620 | @include large { 621 | margin-bottom: 0; 622 | } 623 | } 624 | } 625 | 626 | /** 627 | * @section List of source links 628 | */ 629 | 630 | .book-sources { 631 | font-size: $font-size-small; 632 | 633 | ul { 634 | margin-left: 0; 635 | list-style-type: none; 636 | } 637 | 638 | li { 639 | margin: 0; 640 | } 641 | 642 | li + li { 643 | margin-top: 1px; 644 | } 645 | 646 | a { 647 | display: block; 648 | padding: 0.5rem 1rem; 649 | text-decoration: none; 650 | background-color: $highlight-background-color; 651 | 652 | @include dark-scheme { 653 | background-color: $highlight-background-color-inverted; 654 | } 655 | 656 | &:hover { 657 | background-color: adjust-color( 658 | $highlight-background-color, 659 | $lightness: -2% 660 | ); 661 | 662 | @include dark-scheme { 663 | background-color: adjust-color( 664 | $highlight-background-color-inverted, 665 | $lightness: -2% 666 | ); 667 | } 668 | } 669 | 670 | &::before { 671 | content: '🔗'; 672 | margin-right: 1rem; 673 | } 674 | } 675 | } 676 | 677 | /** 678 | * @section Iframes 679 | */ 680 | 681 | .responsive-iframe { 682 | position: relative; 683 | margin-left: auto; 684 | margin-right: auto; 685 | max-width: 1000px; 686 | height: 0; 687 | padding-top: math.percentage(math.div(1, 1)); 688 | 689 | @include large { 690 | padding-top: math.percentage(math.div(9, 16)); 691 | } 692 | } 693 | 694 | .responsive-iframe__iframe { 695 | position: absolute; 696 | top: 0; 697 | left: 0; 698 | width: 100%; 699 | height: 100%; 700 | 701 | border: 2px solid $darker-text-color; 702 | @include dark-scheme { 703 | border: 2px solid white; 704 | } 705 | } 706 | 707 | .load-iframe { 708 | display: block; 709 | width: 100%; 710 | padding: 0.5rem 1rem; 711 | border: 0; 712 | font-family: inherit; 713 | font-size: inherit; 714 | line-height: inherit; 715 | color: inherit; 716 | cursor: pointer; 717 | 718 | background-color: $link-color; 719 | color: white; 720 | 721 | @include dark-scheme { 722 | background-color: $highlight-background-color-inverted; 723 | color: $link-color-inverted; 724 | } 725 | 726 | &:hover { 727 | background-color: adjust-color($link-color, $lightness: -5%); 728 | 729 | @include dark-scheme { 730 | background-color: adjust-color( 731 | $highlight-background-color-inverted, 732 | $lightness: -2% 733 | ); 734 | } 735 | } 736 | 737 | &:focus { 738 | outline: 1px solid hsl($hue, 90%, 75%); 739 | outline-offset: 3px; 740 | 741 | @include dark-scheme { 742 | outline-color: $link-color-inverted; 743 | } 744 | } 745 | } 746 | 747 | /** 748 | * @section Margin notes 749 | */ 750 | 751 | $margin-note-inner-width: 8rem; 752 | $margin-note-gap: 2rem; 753 | $margin-note-outer-width: $margin-note-inner-width + $margin-note-gap; 754 | $margin-note-breakpoint: $toc-width + $main-max-width + 755 | (2 * $margin-note-outer-width); 756 | 757 | .margin-note { 758 | margin: 0 0 1rem 0; 759 | font-size: $font-size-small; 760 | line-height: 2; 761 | text-transform: uppercase; 762 | text-align: center; 763 | letter-spacing: 0.5px; 764 | word-spacing: 1px; 765 | page-break-after: avoid; 766 | color: $heading-color; 767 | 768 | @include dark-scheme { 769 | color: $heading-color-inverted; 770 | } 771 | 772 | @media screen and (min-width: $margin-note-breakpoint) { 773 | float: left; 774 | display: block; 775 | width: $margin-note-inner-width; 776 | margin-left: -$margin-note-outer-width; 777 | margin-top: 0.3rem; 778 | font-size: $font-size-smallest; 779 | line-height: 1.6; 780 | text-align: right; 781 | text-transform: none; 782 | letter-spacing: inherit; 783 | word-spacing: inherit; 784 | color: inherit; 785 | } 786 | 787 | p { 788 | margin: 0; 789 | line-height: inherit; 790 | } 791 | } 792 | 793 | /** 794 | * Next chapter link 795 | */ 796 | 797 | #next-chapter-link { 798 | margin: 4rem 0; 799 | font-size: 1.2rem; 800 | 801 | a { 802 | display: block; 803 | text-align: right; 804 | text-decoration: none; 805 | 806 | &::before { 807 | content: 'Next chapter: '; 808 | } 809 | 810 | &::after { 811 | content: ' →'; 812 | } 813 | } 814 | } 815 | -------------------------------------------------------------------------------- /_sass/content.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Content Styles 3 | */ 4 | 5 | @import 'variables'; 6 | 7 | /** 8 | * @section Mixins 9 | */ 10 | 11 | @import 'accessible-hide'; 12 | @import 'dark-scheme'; 13 | 14 | /** 15 | * @section Box model fix 16 | */ 17 | 18 | *, 19 | *:before, 20 | *:after { 21 | box-sizing: border-box; 22 | } 23 | 24 | /** 25 | * @section Text selection 26 | */ 27 | 28 | ::selection { 29 | color: $text-color; 30 | background-color: hsl($hue, 100%, 90%); 31 | } 32 | 33 | /** 34 | * @section Root element 35 | */ 36 | 37 | html { 38 | background-color: $background-color; 39 | color: $text-color; 40 | font-family: $base-font; 41 | text-rendering: optimizeLegibility; 42 | font-variant-ligatures: common-ligatures; 43 | 44 | @include dark-scheme { 45 | background-color: $background-color-inverted; 46 | color: $text-color-inverted; 47 | } 48 | } 49 | 50 | /** 51 | * @section Base styles for new HTML5 elements, for old browsers 52 | */ 53 | 54 | main, 55 | section, 56 | nav, 57 | article, 58 | aside, 59 | header, 60 | footer { 61 | display: block; 62 | } 63 | 64 | /** 65 | * @section Headings 66 | */ 67 | 68 | h1, 69 | h2, 70 | h3, 71 | h4, 72 | h5, 73 | h6 { 74 | margin: 3rem 0 1rem; 75 | color: $heading-color; 76 | line-height: $heading-line-height; 77 | page-break-after: avoid; 78 | font-variant-ligatures: common-ligatures discretionary-ligatures contextual; 79 | 80 | @include dark-scheme { 81 | color: $heading-color-inverted; 82 | } 83 | } 84 | 85 | h1 { 86 | font-size: 1.5rem; 87 | } 88 | 89 | h2 { 90 | font-size: 1.4rem; 91 | } 92 | 93 | h3 { 94 | font-size: 1.3rem; 95 | } 96 | 97 | h4 { 98 | font-size: 1.2rem; 99 | } 100 | 101 | h5, 102 | h6 { 103 | font-size: inherit; 104 | } 105 | 106 | h1, 107 | h2, 108 | h3, 109 | h4, 110 | h5, 111 | h6 { 112 | code { 113 | font-family: inherit; 114 | } 115 | } 116 | 117 | /** 118 | * @section All copy text elements 119 | */ 120 | 121 | p, 122 | ul, 123 | ol, 124 | dl, 125 | pre, 126 | blockquote { 127 | margin: 0 0 1rem 0; 128 | line-height: $content-line-height; 129 | @include medium { 130 | line-height: $content-line-height-medium; 131 | } 132 | } 133 | 134 | /** 135 | * @section Lists 136 | */ 137 | 138 | ul, 139 | ol { 140 | margin-left: 2rem; 141 | padding-left: 0; 142 | } 143 | 144 | ul { 145 | list-style-type: disc; 146 | } 147 | 148 | ol { 149 | list-style-type: decimal; 150 | } 151 | 152 | li, 153 | li p { 154 | margin: 0 0 1rem; 155 | } 156 | 157 | /** 158 | * @section Preformatted text and code 159 | */ 160 | 161 | pre, 162 | code, 163 | samp { 164 | background-color: $highlight-background-color; 165 | font-family: $monospace-font; 166 | font-size: 100%; 167 | color: $code-text-color; 168 | overflow-wrap: break-word; 169 | font-variant-ligatures: none; 170 | 171 | @include dark-scheme { 172 | background-color: $highlight-background-color-inverted; 173 | color: $code-text-color-inverted; 174 | } 175 | } 176 | 177 | pre { 178 | padding: 1rem; 179 | overflow: auto; 180 | font-size: 90%; 181 | line-height: 1.8; 182 | border-radius: 3px; 183 | 184 | @include dark-scheme { 185 | scrollbar-color: $text-color-inverted $background-color-inverted; 186 | } 187 | } 188 | 189 | pre code { 190 | background-color: transparent; 191 | color: inherit; 192 | } 193 | 194 | p, 195 | li, 196 | th, 197 | td { 198 | code { 199 | font-family: inherit; 200 | padding: 0 0.2rem; 201 | 202 | @include dark-scheme { 203 | padding: 0; 204 | background-color: transparent; 205 | } 206 | } 207 | } 208 | 209 | /** 210 | * @section Block quotations 211 | */ 212 | 213 | blockquote { 214 | padding: 1px 2rem; 215 | background-color: $highlight-background-color; 216 | color: $citation-text-color; 217 | 218 | @include dark-scheme { 219 | background-color: $highlight-background-color-inverted; 220 | color: inherit; 221 | } 222 | 223 | blockquote { 224 | border: 1px solid #eaeaf0; 225 | } 226 | 227 | h2, 228 | p, 229 | ol, 230 | ul { 231 | margin-top: 0.5rem; 232 | margin-bottom: 0.5rem; 233 | } 234 | 235 | cite { 236 | font-style: normal; 237 | } 238 | } 239 | 240 | /** 241 | * @section Links 242 | */ 243 | 244 | a { 245 | text-decoration: none; 246 | 247 | &:link { 248 | color: $link-color; 249 | text-decoration: underline; 250 | text-decoration-color: $link-border-color; 251 | text-underline-offset: 0.14rem; 252 | transition: text-decoration-color 250ms ease; 253 | 254 | @include dark-scheme { 255 | color: $link-color-inverted; 256 | text-decoration-color: $link-border-color-inverted; 257 | } 258 | } 259 | 260 | &:visited { 261 | color: $link-visited-color; 262 | text-decoration-color: $link-visited-border-color; 263 | 264 | @include dark-scheme { 265 | color: $link-visited-color-inverted; 266 | text-decoration-color: $link-visited-border-color-inverted; 267 | } 268 | } 269 | 270 | &:hover { 271 | text-decoration-color: $link-hover-border-color; 272 | 273 | @include dark-scheme { 274 | text-decoration-color: $link-hover-border-color-inverted; 275 | } 276 | } 277 | 278 | &:focus, 279 | &:active { 280 | color: $link-color; 281 | text-decoration-color: transparent; 282 | outline: 1px solid hsl($hue, 90%, 75%); 283 | outline-offset: 2px; 284 | 285 | @include dark-scheme { 286 | color: $link-color-inverted; 287 | outline-color: $link-color-inverted; 288 | } 289 | } 290 | 291 | & img { 292 | text-decoration: none; 293 | } 294 | } 295 | 296 | /** 297 | * @section Inline quotations 298 | */ 299 | 300 | q { 301 | color: $citation-text-color; 302 | 303 | @include dark-scheme { 304 | color: $citation-text-color-inverted; 305 | } 306 | } 307 | 308 | /** 309 | * @section Data tables 310 | */ 311 | 312 | table { 313 | border-spacing: 0; 314 | margin: 1rem auto; 315 | } 316 | 317 | caption { 318 | font-size: 110%; 319 | font-weight: bold; 320 | margin: 0 0 0.5rem; 321 | } 322 | 323 | th, 324 | td { 325 | border: 1px solid gray; 326 | padding: 0.5rem; 327 | } 328 | 329 | th { 330 | background-color: #fefefe; 331 | 332 | @include dark-scheme { 333 | background-color: transparent; 334 | } 335 | } 336 | 337 | table.compact th { 338 | font-size: 80%; 339 | } 340 | 341 | td p:last-child { 342 | margin-bottom: 0; 343 | } 344 | 345 | /** 346 | * @section Accessible hide utility class 347 | */ 348 | 349 | .accessible-hide { 350 | @extend %accessible-hide; 351 | } 352 | 353 | /** 354 | * @section Images 355 | */ 356 | 357 | .image-full { 358 | display: block; 359 | width: 100%; 360 | } 361 | 362 | .image-max-full { 363 | display: block; 364 | margin: auto; 365 | max-width: 100%; 366 | } 367 | 368 | /** 369 | * @section Responsive Media (img, picture, video, iframe) 370 | */ 371 | 372 | .responsive-media-container { 373 | position: relative; 374 | padding-bottom: 60%; 375 | } 376 | 377 | .responsive-media-object { 378 | position: absolute; 379 | width: 100%; 380 | height: 100%; 381 | border: 0; 382 | } 383 | -------------------------------------------------------------------------------- /_sass/dark-scheme.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Dark color scheme 3 | * 4 | */ 5 | 6 | @mixin dark-scheme { 7 | @media (prefers-color-scheme: dark) { 8 | @content; 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /_sass/fonts.scss: -------------------------------------------------------------------------------- 1 | /* 2 | Font files downloaded from https://fonts.gstatic.com/s/notosans/* 3 | See dl-noto-sans-fonts.sh. 4 | */ 5 | 6 | /* latin */ 7 | @font-face { 8 | font-family: 'Noto Sans'; 9 | font-style: normal; 10 | font-weight: normal; 11 | src: local('Noto Sans'), local('NotoSans'), url(/assets/fonts/noto-sans-normal-normal-latin.woff2) format('woff2'); 12 | unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; 13 | font-display: swap; 14 | } 15 | /* latin-ext */ 16 | @font-face { 17 | font-family: 'Noto Sans'; 18 | font-style: normal; 19 | font-weight: normal; 20 | src: local('Noto Sans'), local('NotoSans'), url(/assets/fonts/noto-sans-normal-normal-latin-ext.woff2) format('woff2'); 21 | unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF; 22 | font-display: swap; 23 | } 24 | 25 | /* latin */ 26 | @font-face { 27 | font-family: 'Noto Sans'; 28 | font-style: italic; 29 | font-weight: normal; 30 | src: local('Noto Sans Italic'), local('NotoSans-Italic'), url(/assets/fonts/noto-sans-italic-normal-latin.woff2) format('woff2'); 31 | unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; 32 | font-display: swap; 33 | } 34 | /* latin-ext */ 35 | @font-face { 36 | font-family: 'Noto Sans'; 37 | font-style: italic; 38 | font-weight: normal; 39 | src: local('Noto Sans Italic'), local('NotoSans-Italic'), url(/assets/fonts/noto-sans-italic-normal-latin-ext.woff2) format('woff2'); 40 | unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF; 41 | font-display: swap; 42 | } 43 | 44 | 45 | /* latin */ 46 | @font-face { 47 | font-family: 'Noto Sans'; 48 | font-style: italic; 49 | font-weight: bold; 50 | src: local('Noto Sans Bold Italic'), local('NotoSans-BoldItalic'), url(/assets/fonts/noto-sans-italic-bold-latin.woff2) format('woff2'); 51 | unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; 52 | font-display: swap; 53 | } 54 | /* latin-ext */ 55 | @font-face { 56 | font-family: 'Noto Sans'; 57 | font-style: italic; 58 | font-weight: bold; 59 | src: local('Noto Sans Bold Italic'), local('NotoSans-BoldItalic'), url(/assets/fonts/noto-sans-italic-bold-latin-ext.woff2) format('woff2'); 60 | unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF; 61 | font-display: swap; 62 | } 63 | 64 | 65 | /* latin */ 66 | @font-face { 67 | font-family: 'Noto Sans'; 68 | font-style: normal; 69 | font-weight: bold; 70 | src: local('Noto Sans Bold'), local('NotoSans-Bold'), url(/assets/fonts/noto-sans-normal-bold-latin.woff2) format('woff2'); 71 | unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD; 72 | font-display: swap; 73 | } 74 | /* latin-ext */ 75 | @font-face { 76 | font-family: 'Noto Sans'; 77 | font-style: normal; 78 | font-weight: bold; 79 | src: local('Noto Sans Bold'), local('NotoSans-Bold'), url(/assets/fonts/noto-sans-normal-bold-latin-ext.woff2) format('woff2'); 80 | unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF; 81 | font-display: swap; 82 | } 83 | -------------------------------------------------------------------------------- /_sass/highlight.scss: -------------------------------------------------------------------------------- 1 | // From https://github.com/richleland/pygments-css/blob/master/manni.css 2 | // https://github.com/richleland/pygments-css/blob/master/UNLICENSE.txt 3 | .highlight .hll { background-color: #ffffcc } 4 | .highlight .c { color: #0099FF; font-style: italic } /* Comment */ 5 | .highlight .err { color: #AA0000; background-color: #FFAAAA } /* Error */ 6 | .highlight .k { color: #006699; font-weight: bold } /* Keyword */ 7 | .highlight .o { color: #555555 } /* Operator */ 8 | .highlight .ch { color: #0099FF; font-style: italic } /* Comment.Hashbang */ 9 | .highlight .cm { color: #0099FF; font-style: italic } /* Comment.Multiline */ 10 | .highlight .cp { color: #009999 } /* Comment.Preproc */ 11 | .highlight .cpf { color: #0099FF; font-style: italic } /* Comment.PreprocFile */ 12 | .highlight .c1 { color: #0099FF; font-style: italic } /* Comment.Single */ 13 | .highlight .cs { color: #0099FF; font-weight: bold; font-style: italic } /* Comment.Special */ 14 | .highlight .gd { background-color: #FFCCCC; border: 1px solid #CC0000 } /* Generic.Deleted */ 15 | .highlight .ge { font-style: italic } /* Generic.Emph */ 16 | .highlight .gr { color: #FF0000 } /* Generic.Error */ 17 | .highlight .gh { color: #003300; font-weight: bold } /* Generic.Heading */ 18 | .highlight .gi { background-color: #CCFFCC; border: 1px solid #00CC00 } /* Generic.Inserted */ 19 | .highlight .go { color: #AAAAAA } /* Generic.Output */ 20 | .highlight .gp { color: #000099; font-weight: bold } /* Generic.Prompt */ 21 | .highlight .gs { font-weight: bold } /* Generic.Strong */ 22 | .highlight .gu { color: #003300; font-weight: bold } /* Generic.Subheading */ 23 | .highlight .gt { color: #99CC66 } /* Generic.Traceback */ 24 | .highlight .kc { color: #006699; font-weight: bold } /* Keyword.Constant */ 25 | .highlight .kd { color: #006699; font-weight: bold } /* Keyword.Declaration */ 26 | .highlight .kn { color: #006699; font-weight: bold } /* Keyword.Namespace */ 27 | .highlight .kp { color: #006699 } /* Keyword.Pseudo */ 28 | .highlight .kr { color: #006699; font-weight: bold } /* Keyword.Reserved */ 29 | .highlight .kt { color: #007788; font-weight: bold } /* Keyword.Type */ 30 | .highlight .m { color: #FF6600 } /* Literal.Number */ 31 | .highlight .s { color: #CC3300 } /* Literal.String */ 32 | .highlight .na { color: #330099 } /* Name.Attribute */ 33 | .highlight .nb { color: #336666 } /* Name.Builtin */ 34 | .highlight .nc { color: #00AA88; font-weight: bold } /* Name.Class */ 35 | .highlight .no { color: #336600 } /* Name.Constant */ 36 | .highlight .nd { color: #9999FF } /* Name.Decorator */ 37 | .highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */ 38 | .highlight .ne { color: #CC0000; font-weight: bold } /* Name.Exception */ 39 | .highlight .nf { color: #CC00FF } /* Name.Function */ 40 | .highlight .nl { color: #9999FF } /* Name.Label */ 41 | .highlight .nn { color: #00CCFF; font-weight: bold } /* Name.Namespace */ 42 | .highlight .nt { color: #330099; font-weight: bold } /* Name.Tag */ 43 | .highlight .nv { color: #003333 } /* Name.Variable */ 44 | .highlight .ow { color: #000000; font-weight: bold } /* Operator.Word */ 45 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */ 46 | .highlight .mb { color: #FF6600 } /* Literal.Number.Bin */ 47 | .highlight .mf { color: #FF6600 } /* Literal.Number.Float */ 48 | .highlight .mh { color: #FF6600 } /* Literal.Number.Hex */ 49 | .highlight .mi { color: #FF6600 } /* Literal.Number.Integer */ 50 | .highlight .mo { color: #FF6600 } /* Literal.Number.Oct */ 51 | .highlight .sa { color: #CC3300 } /* Literal.String.Affix */ 52 | .highlight .sb { color: #CC3300 } /* Literal.String.Backtick */ 53 | .highlight .sc { color: #CC3300 } /* Literal.String.Char */ 54 | .highlight .dl { color: #CC3300 } /* Literal.String.Delimiter */ 55 | .highlight .sd { color: #CC3300; font-style: italic } /* Literal.String.Doc */ 56 | .highlight .s2 { color: #CC3300 } /* Literal.String.Double */ 57 | .highlight .se { color: #CC3300; font-weight: bold } /* Literal.String.Escape */ 58 | .highlight .sh { color: #CC3300 } /* Literal.String.Heredoc */ 59 | .highlight .si { color: #AA0000 } /* Literal.String.Interpol */ 60 | .highlight .sx { color: #CC3300 } /* Literal.String.Other */ 61 | .highlight .sr { color: #33AAAA } /* Literal.String.Regex */ 62 | .highlight .s1 { color: #CC3300 } /* Literal.String.Single */ 63 | .highlight .ss { color: #FFCC33 } /* Literal.String.Symbol */ 64 | .highlight .bp { color: #336666 } /* Name.Builtin.Pseudo */ 65 | .highlight .fm { color: #CC00FF } /* Name.Function.Magic */ 66 | .highlight .vc { color: #003333 } /* Name.Variable.Class */ 67 | .highlight .vg { color: #003333 } /* Name.Variable.Global */ 68 | .highlight .vi { color: #003333 } /* Name.Variable.Instance */ 69 | .highlight .vm { color: #003333 } /* Name.Variable.Magic */ 70 | .highlight .il { color: #FF6600 } /* Literal.Number.Integer.Long */ 71 | 72 | @include dark-scheme { 73 | // From https://github.com/richleland/pygments-css/blob/master/native.css 74 | // https://github.com/richleland/pygments-css/blob/master/UNLICENSE.txt 75 | .highlight .hll { background-color: #404040 } 76 | .highlight .c { color: #999999; font-style: italic } /* Comment */ 77 | .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ 78 | .highlight .esc { color: #d0d0d0 } /* Escape */ 79 | .highlight .g { color: #d0d0d0 } /* Generic */ 80 | .highlight .k { color: #6ab825; font-weight: bold } /* Keyword */ 81 | .highlight .l { color: #d0d0d0 } /* Literal */ 82 | .highlight .n { color: #d0d0d0 } /* Name */ 83 | .highlight .o { color: #d0d0d0 } /* Operator */ 84 | .highlight .x { color: #d0d0d0 } /* Other */ 85 | .highlight .p { color: #d0d0d0 } /* Punctuation */ 86 | .highlight .ch { color: #999999; font-style: italic } /* Comment.Hashbang */ 87 | .highlight .cm { color: #999999; font-style: italic } /* Comment.Multiline */ 88 | .highlight .cp { color: #cd2828; font-weight: bold } /* Comment.Preproc */ 89 | .highlight .cpf { color: #999999; font-style: italic } /* Comment.PreprocFile */ 90 | .highlight .c1 { color: #999999; font-style: italic } /* Comment.Single */ 91 | .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ 92 | .highlight .gd { color: #d22323 } /* Generic.Deleted */ 93 | .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ 94 | .highlight .gr { color: #d22323 } /* Generic.Error */ 95 | .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ 96 | .highlight .gi { color: #589819 } /* Generic.Inserted */ 97 | .highlight .go { color: #cccccc } /* Generic.Output */ 98 | .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ 99 | .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ 100 | .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ 101 | .highlight .gt { color: #d22323 } /* Generic.Traceback */ 102 | .highlight .kc { color: #6ab825; font-weight: bold } /* Keyword.Constant */ 103 | .highlight .kd { color: #6ab825; font-weight: bold } /* Keyword.Declaration */ 104 | .highlight .kn { color: #6ab825; font-weight: bold } /* Keyword.Namespace */ 105 | .highlight .kp { color: #6ab825 } /* Keyword.Pseudo */ 106 | .highlight .kr { color: #6ab825; font-weight: bold } /* Keyword.Reserved */ 107 | .highlight .kt { color: #6ab825; font-weight: bold } /* Keyword.Type */ 108 | .highlight .ld { color: #d0d0d0 } /* Literal.Date */ 109 | .highlight .m { color: #3677a9 } /* Literal.Number */ 110 | .highlight .s { color: #ed9d13 } /* Literal.String */ 111 | .highlight .na { color: #bbbbbb } /* Name.Attribute */ 112 | .highlight .nb { color: #24909d } /* Name.Builtin */ 113 | .highlight .nc { color: #447fcf; text-decoration: underline } /* Name.Class */ 114 | .highlight .no { color: #40ffff } /* Name.Constant */ 115 | .highlight .nd { color: #ffa500 } /* Name.Decorator */ 116 | .highlight .ni { color: #d0d0d0 } /* Name.Entity */ 117 | .highlight .ne { color: #bbbbbb } /* Name.Exception */ 118 | .highlight .nf { color: #447fcf } /* Name.Function */ 119 | .highlight .nl { color: #d0d0d0 } /* Name.Label */ 120 | .highlight .nn { color: #447fcf; text-decoration: underline } /* Name.Namespace */ 121 | .highlight .nx { color: #d0d0d0 } /* Name.Other */ 122 | .highlight .py { color: #d0d0d0 } /* Name.Property */ 123 | .highlight .nt { color: #6ab825; font-weight: bold } /* Name.Tag */ 124 | .highlight .nv { color: #40ffff } /* Name.Variable */ 125 | .highlight .ow { color: #6ab825; font-weight: bold } /* Operator.Word */ 126 | .highlight .w { color: #666666 } /* Text.Whitespace */ 127 | .highlight .mb { color: #3677a9 } /* Literal.Number.Bin */ 128 | .highlight .mf { color: #3677a9 } /* Literal.Number.Float */ 129 | .highlight .mh { color: #3677a9 } /* Literal.Number.Hex */ 130 | .highlight .mi { color: #3677a9 } /* Literal.Number.Integer */ 131 | .highlight .mo { color: #3677a9 } /* Literal.Number.Oct */ 132 | .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ 133 | .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ 134 | .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ 135 | .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ 136 | .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ 137 | .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ 138 | .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ 139 | .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ 140 | .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ 141 | .highlight .sx { color: #ffa500 } /* Literal.String.Other */ 142 | .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ 143 | .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ 144 | .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ 145 | .highlight .bp { color: #24909d } /* Name.Builtin.Pseudo */ 146 | .highlight .fm { color: #447fcf } /* Name.Function.Magic */ 147 | .highlight .vc { color: #40ffff } /* Name.Variable.Class */ 148 | .highlight .vg { color: #40ffff } /* Name.Variable.Global */ 149 | .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ 150 | .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ 151 | .highlight .il { color: #3677a9 } /* Literal.Number.Integer.Long */ 152 | } 153 | 154 | // Changes by molily 155 | // In JavaScript/TypeScript, err is used for the `template literal`. 156 | // Make it look like a normal .s1 (Literal.String.Single) instead of an error. 157 | .language-typescript, .language-js { 158 | .highlight .err { 159 | color: #CC3300; 160 | background-color: transparent; 161 | @include dark-scheme { 162 | color: #ed9d13; 163 | background-color: transparent; 164 | } 165 | } 166 | } 167 | -------------------------------------------------------------------------------- /_sass/mixins.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * @section Mixins 3 | * 4 | */ 5 | 6 | @mixin medium { 7 | @media screen and (min-width: $breakpoint-medium) { 8 | @content; 9 | } 10 | } 11 | 12 | @mixin large { 13 | @media screen and (min-width: $breakpoint-large) { 14 | @content; 15 | } 16 | } 17 | 18 | @mixin high-dpi { 19 | @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 2dppx) { 20 | @content; 21 | } 22 | } -------------------------------------------------------------------------------- /_sass/reset.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Careful Reset 3 | */ 4 | 5 | /** 6 | * @section Block Elements: Reset margin, padding and border 7 | * 8 | */ 9 | 10 | html, body, 11 | h1, h2, h3, h4, h5, h6, 12 | div, 13 | p, 14 | blockquote, 15 | pre, 16 | dl, dt, dd, 17 | ol, ul, li, 18 | form, fieldset, 19 | table, caption, tbody, tfoot, thead, tr, th, td { 20 | margin: 0; 21 | padding: 0; 22 | border: 0; 23 | } 24 | 25 | /** 26 | * @section Reset Headline Font 27 | * 28 | */ 29 | 30 | h1, h2, h3, h4, h5, h6 { 31 | font-weight: normal; 32 | font-size: 100%; 33 | } 34 | 35 | /** 36 | * @section Lists 37 | * 38 | * No list numbering and item markers 39 | */ 40 | 41 | ol, ul { 42 | list-style: none; 43 | } 44 | 45 | /** 46 | * @section Tables 47 | * 48 | * Collapse borders and reset table headers 49 | */ 50 | 51 | table { 52 | border-collapse: collapse; 53 | } 54 | 55 | caption, th, td { 56 | text-align: left; 57 | font-weight: normal; 58 | } 59 | 60 | /** 61 | * @section Quotes 62 | * 63 | */ 64 | 65 | :lang(en) q { 66 | quotes: "“" "”" "‘" "’"; 67 | } 68 | 69 | :lang(de) q { 70 | quotes: "»" "«" "›" "‹"; 71 | } 72 | 73 | /** 74 | * @section Images 75 | * 76 | * Suppress border 77 | */ 78 | 79 | a img { 80 | border: 0; 81 | } -------------------------------------------------------------------------------- /_sass/variables.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Variables 3 | * 4 | */ 5 | 6 | /** 7 | * @section Colors 8 | * 9 | */ 10 | 11 | // Accent colors 12 | $hue: 258; 13 | $hue2: 220; 14 | 15 | // Text and background colors 16 | $background-color: white; 17 | $text-color: #252527; 18 | $darker-text-color: #666; 19 | $heading-color: hsl($hue, 60%, 25%); 20 | $highlight-background-color: hsl($hue2, 50%, 98%); 21 | $code-text-color: #009; 22 | $citation-text-color: #4a4a60; 23 | 24 | // Inverted text and background colors 25 | $background-color-inverted: #3c3d5b; 26 | $text-color-inverted: #d7d7db; 27 | // Original: #8a77b3 28 | $darker-text-color-inverted: hsl(259, 35%, 70%); 29 | $heading-color-inverted: $darker-text-color-inverted; 30 | $medium-background-color-inverted: #31324c; 31 | $dark-background-color-inverted: #140a32; 32 | $highlight-background-color-inverted: #22233d; 33 | $code-text-color-inverted: hsl(170, 55%, 70%); 34 | $citation-text-color-inverted: #b0b0b0; 35 | 36 | // Link colors 37 | $link-color: hsl($hue2, 100%, 30%); 38 | $link-border-color: desaturate(lighten($link-color, 40%), 60%); 39 | 40 | $link-visited-color: $text-color; 41 | $link-visited-border-color: lighten($link-border-color, 1%); 42 | 43 | $link-hover-border-color: #8080c0; 44 | 45 | // Inverted link colors 46 | // $link-color-inverted-hue: 57; 47 | 48 | $link-color-inverted: #17c6d4; 49 | $link-border-color-inverted: #118db9; 50 | 51 | $link-visited-color-inverted: #0f8e9a; 52 | $link-visited-border-color-inverted: $link-visited-color-inverted; 53 | 54 | $link-hover-border-color-inverted: lighten($link-border-color-inverted, 5%); 55 | 56 | /** 57 | * @section Typography 58 | * 59 | */ 60 | 61 | // Font stack without webfont 62 | $sans-serif-font: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif; 63 | // Font stack with webfont 64 | $base-font: 'Noto Sans', $sans-serif-font; 65 | 66 | $monospace-font: 'Monaco', 'Consolas', 'Droid Sans Mono', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', 'Liberation Mono', 'Courier New', monospace; 67 | 68 | $content-line-height: 1.8; 69 | $content-line-height-medium: 2; 70 | $heading-line-height: 1.5; 71 | 72 | /** 73 | * @section Responsive layout 74 | * 75 | */ 76 | 77 | $breakpoint-medium: 30rem; 78 | $breakpoint-large: 55rem; 79 | -------------------------------------------------------------------------------- /about.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: About 4 | description: About the author of this book and how to send feedback 5 | --- 6 | 7 | # About 8 | 9 | Author: [Mathias Schäfer (molily)](https://molily.de) 10 | 11 | Mathias is a software developer with a focus on web development and JavaScript web applications. 12 | 13 | Mathias is working for [9elements](https://9elements.com), a software and design agency. 14 | 15 | [Follow molily on Mastodon](https://mastodon.social/@molily). 16 | 17 | **Please send feedback and corrections to [molily@mailbox.org](mailto:molily@mailbox.org) or file an issue on GitHub.** 18 | 19 | First published on . 20 | 21 | 22 | -------------------------------------------------------------------------------- /acknowledgements.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Acknowledgements 4 | description: Thanks to those who helped me writing this book 5 | --- 6 | 7 | # Acknowledgements 8 | 9 | This book would not be possible without the support and input from many individuals. I would like to thank everyone in the Angular, JavaScript and web development communities who not only shares knowledge and works on open source tools, but also advocates for inclusive communities and software. 10 | 11 | Thanks to the teams at 9elements, Diebold Nixdorf and Keysight Technologies for the opportunity to work on first-class Angular applications. Thanks for the challenges, resources and patience that allowed me to research automated testing in detail. 12 | 13 | Thanks to [Netanel Basal](https://netbasal.com/) for valuable feedback on the book, for creating Spectator and for many helpful articles on Angular and testing. 14 | 15 | Thanks to [Nils Binder](https://ichimnetz.com/) for helping with the design, including the dark color scheme. Thanks to Melina Jacob for designing the e-book cover. 16 | 17 | Thanks to [Tim Deschryver](https://timdeschryver.dev/), [Kent C. Dodds](https://kentcdodds.com/), [Kara Erickson](https://twitter.com/karaforthewin), [Asim Hussain](https://asim.dev/), [Tracy Lee](https://twitter.com/ladyleet), [Brandon Roberts](https://brandonroberts.dev/), [Jesse Palmer](https://jesselpalmer.com/), Corinna Cohn, [Mike Giambalvo](https://twitter.com/heathkit), [Craig Nishina](https://twitter.com/cnishina), [Lucas F. Costa](https://lucasfcosta.com/) and [Jessica Sachs](https://jess.sh/) for insights on Angular, RxJS and automated testing. 18 | 19 | 20 | -------------------------------------------------------------------------------- /angular-testing-principles.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Angular testing principles 4 | description: Dependency injection, mocking, starting the Karma test suite 5 | --- 6 | 7 | # Angular testing principles 8 | 9 | 16 | 17 | ## Testability 18 | 19 | In contrast to other popular front-end JavaScript libraries, Angular is an opinionated, comprehensive framework that covers all important aspects of developing a JavaScript web application. Angular provides high-level structure, low-level building blocks and means to bundle everything together into a usable application. 20 | 21 | 22 | 23 | The complexity of Angular cannot be understood without considering automated testing. Why is an Angular application structured into Components, Services, Modules, etc.? Why are the parts intertwined the way they are? Why do all parts of an Angular application apply the same patterns? 24 | 25 | An important reason is **testability**. Angular’s architecture guarantees that all application parts can be tested easily in a similar way. 26 | 27 | 28 | 29 | We know from experience that code that is easy to test is also simpler, better structured, easier to read and easier to understand. The main technique of writing testable code is to break code into smaller chunks that “do one thing and do it well”. Then couple the chunks loosely. 30 | 31 | ## Dependency injection and faking 32 | 33 | A major design pattern for loose coupling is **dependency injection** and the underlying **inversion of control**. Instead of creating a dependency itself, an application part merely declares the dependency. The tedious task of creating and providing the dependency is delegated to an *injector* that sits on top. 34 | 35 | This division of work decouples an application part from its dependencies: One part does not need to know how to set up a dependency, let alone the dependency’s dependencies and so forth. 36 | 37 | 38 | 39 | Dependency injection turns tight coupling into loose coupling. A certain application part no longer depends on a specific class, function, object or other value. It rather depends on an abstract **token** that can be traded in for a concrete implementation. The injector takes the token and exchanges it for a real value. 40 | 41 | 42 | 43 | This is of immense importance for automated testing. In our test, we can decide how to deal with a dependency: 44 | 45 | - We can either provide an **original**, fully-functional implementation. In this case, we are writing an [integration test](../testing-principles/#integration-tests) that includes direct and indirect dependencies. 46 | - Or we provide a **fake** implementation that does not have side effects. In this case, we are writing a [unit test](../testing-principles/#unit-tests) that tries to test the application part in *isolation*. 47 | 48 | A large portion of the time spent while writing tests is spent on decoupling an application part from its dependencies. This guide will teach you how to set up the test environment, isolate an application part and reconnect it with equivalent fake objects. 49 | 50 |
51 | - [Angular guide: Dependency injection](https://angular.io/guide/dependency-injection) 52 |
53 | 54 | ## Testing tools 55 | 56 | Angular provides solid testing tools out of the box. When you create an Angular project using the command line interface, it comes with a fully-working testing setup for unit, integration and end-to-end tests. 57 | 58 | 59 | 60 | The Angular team already made decisions for you: [Jasmine](https://jasmine.github.io/) as testing framework and [Karma](https://karma-runner.github.io/) as test runner. Implementation and test code is bundled with [Webpack](https://webpack.js.org). Application parts are typically tested inside Angular’s [TestBed](https://angular.io/api/core/testing/TestBed). 61 | 62 | This setup is a trade-off with strengths and weaknesses. Since it is just one possible way to test Angular applications, you can compile your own testing tool chain. 63 | 64 | 65 | 66 | For example, some Angular developers use [Jest](https://jestjs.io/) instead of Jasmine and Karma. Some use [Spectator](../testing-components-with-spectator/#testing-components-with-spectator) or the [Angular Testing Library](https://github.com/testing-library/angular-testing-library) instead of using `TestBed` directly. 67 | 68 | These alternatives are not better or worse, they simply make different trade-offs. This guide uses Jasmine and Karma for unit and integration tests. Later, you will learn about Spectator. 69 | 70 | Once you have reached the limits of a particular setup, you should investigate whether alternatives make testing your application easier, faster and more reliable. 71 | 72 | ## Testing conventions 73 | 74 | Angular offers some tools and conventions on testing. By design, they are flexible enough to support different ways of testing. So you need to decide how to apply them. 75 | 76 | 77 | 78 | This freedom of choice benefits experts, but confuses beginners. In your project, there should be one preferable way how to test a specific application part. You should make choices and set up project-wide conventions and patterns. 79 | 80 | 81 | 82 | The testing tools that ship with Angular are low-level. They merely provide the basic operations. If you use these tools directly, your tests become messy, repetitive and hard to maintain. 83 | 84 | Therefore, you should create **high-level testing tools** that cast your conventions into code in order to write short, readable and understandable tests. 85 | 86 | This guide values strong conventions and introduces helper functions that codify these conventions. Again, your mileage may vary. You are free to adapt these tools to your needs or build other testing helpers. 87 | 88 | ## Running the unit and integration tests 89 | 90 | The Angular command line interface (CLI) allows you to run the unit, integration and end-to-end tests. If you have not installed the CLI yet or need to update to the latest version, run this command on your shell: 91 | 92 | ``` 93 | npm install -g @angular/cli 94 | ``` 95 | 96 | This installs Angular CLI globally so the `ng` command can be used everywhere. `ng` itself does nothing but exposing a couple of Angular-specific commands. 97 | 98 | For example, `ng new` creates a new Angular project directory with a ready-to-use application scaffold. `ng serve` starts a development server, and `ng build` makes a build. 99 | 100 | The command for starting the unit and integration tests is: 101 | 102 | ``` 103 | ng test 104 | ``` 105 | 106 | First, this command finds all files in the directory tree that match the pattern `.spec.ts`. Using Webpack, it compiles them into a JavaScript bundle, together with its dependencies. The bundle code also initializes the Angular testing environment – the `TestBed`. 107 | 108 | Typically, an Angular application loads and starts an `AppModule`. This startup is called bootstrapping. The `AppModule` then imports other Modules, Components, Services, etc. This way, the bundler finds all parts of the application. 109 | 110 | The test bundle works differently. It does not start with one Module in order to walk through its dependencies. It merely imports all files whose name ends with `.spec.ts`. 111 | 112 | 115 | 116 | Each **`.spec.ts` file** represents a test. Typically, one `.spec.ts` file contains at least one Jasmine test suite (more on that in the next chapter). The `.spec.ts` files are located in the same directory as the implementation code. 117 | 118 | In our example application, the `CounterComponent` is located in [src/app/components/counter/counter.component.ts](https://github.com/9elements/angular-workshop/blob/main/src/app/components/counter/counter.component.ts). The corresponding test file sits in [src/app/components/counter/counter.component.spec.ts](https://github.com/9elements/angular-workshop/blob/main/src/app/components/counter/counter.component.spec.ts). This is an Angular convention, not a technical necessity, and we are going to stick to it. 119 | 120 | 121 | 122 | Second, `ng test` launches Karma, the test runner. Karma starts a development server at [http://localhost:9876/](http://localhost:9876/) that serves the JavaScript bundles compiled by Webpack. 123 | 124 | Karma then launches one or more browsers. The idea of Karma is to run the same tests in different browsers to ensure cross-browser interoperability. All widely used browsers are supported: Chrome, Internet Explorer, Edge, Firefox and Safari. Per default, Karma starts Chrome. 125 | 126 | 127 | 128 | The launched browser navigates to `http://localhost:9876/`. As mentioned, this site serves the test runner and the test bundle. The tests start immediately. You can track the progress and read the results in the browser and on the shell. 129 | 130 | When running the tests in the [counter project](../example-applications/#the-counter-component), the browser output looks like this: 131 | 132 | 133 | 46 specs, 0 failures 134 | 135 | 136 | This is the shell output: 137 | 138 | ``` 139 | INFO [karma-server]: Karma v5.0.7 server started at http://0.0.0.0:9876/ 140 | INFO [launcher]: Launching browsers Chrome with concurrency unlimited 141 | INFO [launcher]: Starting browser Chrome 142 | WARN [karma]: No captured browser, open http://localhost:9876/ 143 | INFO [Chrome 84.0.4147.135 (Mac OS 10.15.6)]: Connected on socket yH0-wtoVtflRWMoWAAAA with id 76614320 144 | Chrome 84.0.4147.135 (Mac OS 10.15.6): Executed 46 of 46 SUCCESS (0.394 secs / 0.329 secs) 145 | TOTAL: 46 SUCCESS 146 | ``` 147 | 148 | Webpack watches changes on the `.spec.ts` files and files imported by them. When you change the implementation code, `counter.component.ts` for example, or the test code, `counter.component.spec.ts` for example, Webpack automatically re-compiles the bundle and pushes it to the open browsers. All tests will be restarted. 149 | 150 | 151 | 152 | This feedback cycle allows you to work on the implementation and test code side-by-side. This is important for test-driven development. You change the implementation and expect the test to fail – the test is “red”. You adapt the test so it passes again – the test is “green”. Or you write a failing test first, then adapt the implementation until the test passes. 153 | 154 | Test-driven development means letting the red-green cycle guide your development. 155 | 156 |
157 | - [Angular CLI reference: ng test](https://angular.io/cli/test) 158 |
159 | 160 | ## Configuring Karma and Jasmine 161 | 162 | Karma and Jasmine are configured in the file `karma.conf.js` in the project’s root directory. Since Angular 15, the Angular CLI does not create this file per default. If it does not exist, you can create it using this shell command: 163 | 164 | ``` 165 | ng generate config karma 166 | ``` 167 | 168 | There are many configuration options and plenty of plugins, so we will only look at a few. 169 | 170 | 171 | 172 | As mentioned, the standard configuration runs the tests in the Chrome browser. To run the tests in other browsers, we need to install different **launchers**. 173 | 174 | Each launcher needs to be loaded in the `plugins` array: 175 | 176 | ```javascript 177 | plugins: [ 178 | require('karma-jasmine'), 179 | require('karma-chrome-launcher'), 180 | require('karma-jasmine-html-reporter'), 181 | require('karma-coverage'), 182 | require('@angular-devkit/build-angular/plugins/karma') 183 | ], 184 | ``` 185 | 186 | There is already one launcher, `karma-chrome-launcher`. This is an npm package. 187 | 188 | To install other launchers, we first need to install the respective npm package. Let us install the Firefox launcher. Run this shell command: 189 | 190 | ``` 191 | npm install --save-dev karma-firefox-launcher 192 | ``` 193 | 194 | Then we require the package in `karma.conf.js`: 195 | 196 | ```javascript 197 | plugins: [ 198 | require('karma-jasmine'), 199 | require('karma-chrome-launcher'), 200 | require('karma-firefox-launcher'), 201 | require('karma-jasmine-html-reporter'), 202 | require('karma-coverage'), 203 | require('@angular-devkit/build-angular/plugins/karma'), 204 | ], 205 | ``` 206 | 207 | To run the tests in Firefox as well, we need to add the Firefox to the browsers list: `browsers: ['Chrome']` becomes `browsers: ['Chrome', 'Firefox']`. 208 | 209 | Karma will now start two browsers to run the tests in parallel. 210 | 211 | 212 | 213 | Another important concept of Karma are **reporters**. They format and output the test results. In the default configuration, three reporters are active: 214 | 215 | 1. The built-in `progress` reporter outputs text on the shell. While the tests are running, it outputs the progress: 216 | 217 | `Chrome 84.0.4147.135 (Mac OS 10.15.6): Executed 9 of 46 SUCCESS (0.278 secs / 0.219 secs)` 218 | 219 | And finally: 220 | 221 | `Chrome 84.0.4147.135 (Mac OS 10.15.6): Executed 46 of 46 SUCCESS (0.394 secs / 0.329 secs)`
222 | `TOTAL: 46 SUCCESS` 223 | 224 | 2. The standard HTML reporter `kjhtml` (npm package: `karma-jasmine-html-reporter`) renders the results in the browser. 225 | 226 | 227 | 46 specs, 0 failures 228 | 229 | 230 | 3. The coverage reporter (npm package: `karma-coverage`) creates the test coverage report. See [measuring code coverage](../measuring-code-coverage/#measuring-code-coverage). 231 | 232 | By editing the `reporters` array, you can add reporters or replace the existing ones: 233 | 234 | ```javascript 235 | reporters: ['progress', 'kjhtml'], 236 | ``` 237 | 238 | For example, to add a reporter that creates JUnit XML reports, first install the npm package: 239 | 240 | ``` 241 | npm install --save-dev karma-junit-reporter 242 | ``` 243 | 244 | Next, require it as a plugin: 245 | 246 | ```javascript 247 | plugins: [ 248 | require('karma-jasmine'), 249 | require('karma-chrome-launcher'), 250 | require('karma-jasmine-html-reporter'), 251 | require('karma-coverage'), 252 | require('karma-junit-reporter'), 253 | require('@angular-devkit/build-angular/plugins/karma'), 254 | ], 255 | ``` 256 | 257 | Finally, add the reporter: 258 | 259 | ```javascript 260 | reporters: ['progress', 'kjhtml', 'junit'], 261 | ``` 262 | 263 | After running the tests with `ng test`, you will find an XML report file in the project directory. 264 | 265 | 266 | 267 | The configuration for the Jasmine adapter is located in `jasmine` object inside the `client` object: 268 | 269 | ```javascript 270 | client: { 271 | jasmine: { 272 | // you can add configuration options for Jasmine here 273 | // the possible options are listed at https://jasmine.github.io/api/edge/Configuration.html 274 | // for example, you can disable the random execution with `random: false` 275 | // or set a specific seed with `seed: 4321` 276 | }, 277 | clearContext: false // leave Jasmine Spec Runner output visible in browser 278 | }, 279 | ``` 280 | 281 | This guide recommends to activate one useful Jasmine configuration option: `failSpecWithNoExpectations` lets the test fail if it does not contain at least one expectation. (More on [expectations](../test-suites-with-jasmine/#expectations) later.) In almost all cases, specs without expectations stem from an error in the test code. 282 | 283 | ```javascript 284 | client: { 285 | jasmine: { 286 | failSpecWithNoExpectations: true, 287 | }, 288 | clearContext: false // leave Jasmine Spec Runner output visible in browser 289 | }, 290 | ``` 291 | 292 |
293 | - [Karma documentation: Configuration File](https://karma-runner.github.io/6.4/config/configuration-file.html) 294 | - [Karma documentation: Plugins](https://karma-runner.github.io/6.4/config/plugins.html) 295 | - [npm: List of Karma plugins](https://www.npmjs.com/search?q=keywords:karma-plugin) 296 | - [Jasmine reference: Configuration options](https://jasmine.github.io/api/edge/Configuration.html) 297 |
298 | 299 | 300 | -------------------------------------------------------------------------------- /assets/css/book.scss: -------------------------------------------------------------------------------- 1 | --- 2 | # By using these dashes, the file will be compiled to a separate .css 3 | --- 4 | 5 | @charset 'utf-8'; 6 | 7 | @import 'book-partial'; 8 | -------------------------------------------------------------------------------- /assets/fonts/LICENSE.md: -------------------------------------------------------------------------------- 1 | # Noto Sans Font License 2 | 3 | The Noto Sans font files are licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). 4 | 5 | See Noto Sans on [Google fonts](https://fonts.google.com/specimen/Noto+Sans). 6 | -------------------------------------------------------------------------------- /assets/fonts/dl-noto-sans-fonts.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # Fonts from: 4 | # https://fonts.googleapis.com/css?family=Noto+Sans:400,400i,700,700i&display=swap 5 | 6 | wget -O noto-sans-normal-normal-latin.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0IIpQlx3QUlC5A4PNr5TRASf6M7Q.woff2 7 | wget -O noto-sans-normal-normal-latin-ext.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0IIpQlx3QUlC5A4PNr6zRASf6M7VBj.woff2 8 | 9 | wget -O noto-sans-normal-bold-latin.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0NIpQlx3QUlC5A4PNjXhFVZNyBx2pqPA.woff2 10 | wget -O noto-sans-normal-bold-latin-ext.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0NIpQlx3QUlC5A4PNjXhFVatyBx2pqPIif.woff2 11 | 12 | wget -O noto-sans-italic-normal-latin.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0OIpQlx3QUlC5A4PNr4ARCQ_mu72Bi.woff2 13 | wget -O noto-sans-italic-normal-latin-ext.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0OIpQlx3QUlC5A4PNr4ARMQ_mu72BiBLE.woff2 14 | 15 | wget -O noto-sans-italic-bold-latin.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0TIpQlx3QUlC5A4PNr4Az5ZuyDzW1IPrie.woff2 16 | wget -O noto-sans-italic-bold-latin-ext.woff2 https://fonts.gstatic.com/s/notosans/v11/o-0TIpQlx3QUlC5A4PNr4Az5ZuyNzW1IPriezag.woff2 17 | -------------------------------------------------------------------------------- /assets/fonts/noto-sans-italic-bold-latin-ext.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-italic-bold-latin-ext.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-italic-bold-latin.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-italic-bold-latin.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-italic-normal-latin-ext.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-italic-normal-latin-ext.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-italic-normal-latin.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-italic-normal-latin.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-normal-bold-latin-ext.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-normal-bold-latin-ext.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-normal-bold-latin.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-normal-bold-latin.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-normal-normal-latin-ext.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-normal-normal-latin-ext.woff2 -------------------------------------------------------------------------------- /assets/fonts/noto-sans-normal-normal-latin.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/fonts/noto-sans-normal-normal-latin.woff2 -------------------------------------------------------------------------------- /assets/img/README: -------------------------------------------------------------------------------- 1 | /usr/local/Cellar/mozjpeg/4.0.3/bin/cjpeg -quality 85 -optimize -outfile flying-probe-672-q85.jpg ~/Documents/testing-angular-flying-probe/flying-probe-672.png 2 | /usr/local/Cellar/mozjpeg/4.0.3/bin/cjpeg -quality 65 -optimize -outfile flying-probe-1344-q65.jpg ~/Documents/testing-angular-flying-probe/flying-probe-1344.png 3 | 4 | cwebp -q 80 ~/Documents/testing-angular-flying-probe/flying-probe-672.png -o flying-probe-672-cwebp-q80.webp 5 | cwebp -q 80 ~/Documents/testing-angular-flying-probe/flying-probe-1344.png -o flying-probe-1344-cwebp-q80.webp 6 | cwebp -q 80 ~/Documents/testing-angular-flying-probe/flying-probe-2-1-2085.png -o flying-probe-2-1-2085-cwebp-q80.webp 7 | 8 | cavif --quality 60 ~/Documents/testing-angular-flying-probe/flying-probe-672.png -o flying-probe-672-cavif-q60.avif 9 | cavif --quality 50 ~/Documents/testing-angular-flying-probe/flying-probe-1344.png -o flying-probe-1344-cavif-q50.avif 10 | 11 | # avifenc -j 10 --min 0 --max 40 -s 0 ~/Documents/testing-angular-flying-probe/flying-probe-1344.png flying-probe-1344-avifenc-min-0-max-40.avif 12 | -------------------------------------------------------------------------------- /assets/img/code-coverage-flickr-search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/code-coverage-flickr-search.png -------------------------------------------------------------------------------- /assets/img/code-coverage-photo-item-uncovered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/code-coverage-photo-item-uncovered.png -------------------------------------------------------------------------------- /assets/img/code-coverage-photo-item.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/code-coverage-photo-item.png -------------------------------------------------------------------------------- /assets/img/cypress-choose-browser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/cypress-choose-browser.png -------------------------------------------------------------------------------- /assets/img/cypress-choose-testing-type.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/cypress-choose-testing-type.png -------------------------------------------------------------------------------- /assets/img/cypress-runner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/cypress-runner.png -------------------------------------------------------------------------------- /assets/img/cypress-spec-failed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/cypress-spec-failed.png -------------------------------------------------------------------------------- /assets/img/cypress-spec.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/cypress-spec.png -------------------------------------------------------------------------------- /assets/img/cypress-tests.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/cypress-tests.png -------------------------------------------------------------------------------- /assets/img/favicons/favicon-144x144.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/favicons/favicon-144x144.png -------------------------------------------------------------------------------- /assets/img/favicons/favicon-16x16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/favicons/favicon-16x16.png -------------------------------------------------------------------------------- /assets/img/favicons/favicon-194x194.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/favicons/favicon-194x194.png -------------------------------------------------------------------------------- /assets/img/favicons/favicon-32x32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/favicons/favicon-32x32.png -------------------------------------------------------------------------------- /assets/img/favicons/favicon-96x96.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/favicons/favicon-96x96.png -------------------------------------------------------------------------------- /assets/img/favicons/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/favicons/favicon.ico -------------------------------------------------------------------------------- /assets/img/favicons/favicon.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /assets/img/flying-probe-1200-ogimage-85.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-1200-ogimage-85.jpg -------------------------------------------------------------------------------- /assets/img/flying-probe-1344-cavif-q50.avif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-1344-cavif-q50.avif -------------------------------------------------------------------------------- /assets/img/flying-probe-1344-cwebp-q80.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-1344-cwebp-q80.webp -------------------------------------------------------------------------------- /assets/img/flying-probe-1344-q65.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-1344-q65.jpg -------------------------------------------------------------------------------- /assets/img/flying-probe-2-1-2085-cwebp-q80.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-2-1-2085-cwebp-q80.webp -------------------------------------------------------------------------------- /assets/img/flying-probe-672-cavif-q60.avif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-672-cavif-q60.avif -------------------------------------------------------------------------------- /assets/img/flying-probe-672-cwebp-q80.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-672-cwebp-q80.webp -------------------------------------------------------------------------------- /assets/img/flying-probe-672-q85.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/flying-probe-672-q85.jpg -------------------------------------------------------------------------------- /assets/img/jasmine-debug-runner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/jasmine-debug-runner.png -------------------------------------------------------------------------------- /assets/img/jasmine-debugger.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/jasmine-debugger.png -------------------------------------------------------------------------------- /assets/img/jasmine-dom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/jasmine-dom.png -------------------------------------------------------------------------------- /assets/img/karma-jasmine-html-reporter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/karma-jasmine-html-reporter.png -------------------------------------------------------------------------------- /assets/img/karma-select-context.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/karma-select-context.png -------------------------------------------------------------------------------- /assets/img/karma-success.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/img/karma-success.png -------------------------------------------------------------------------------- /assets/js/collapse-toc.js: -------------------------------------------------------------------------------- 1 | (function () { 2 | 'use strict'; 3 | 4 | function installCollapseTOC() { 5 | var chapterLinks = document.querySelectorAll('#toc-tree > li > a'); 6 | for (var i = 0, l = chapterLinks.length; i < l; i++) { 7 | var chapterLink = chapterLinks[i]; 8 | if (chapterLink.pathname !== location.pathname) { 9 | var ol = chapterLink.nextElementSibling; 10 | if (ol) { 11 | ol.className += ' collapsed'; 12 | } 13 | } 14 | } 15 | } 16 | 17 | if (document.body.querySelectorAll && 'nextElementSibling' in document.body) { 18 | installCollapseTOC(); 19 | } 20 | })(); 21 | -------------------------------------------------------------------------------- /assets/js/highlight-toc.js: -------------------------------------------------------------------------------- 1 | (function () { 2 | 'use strict'; 3 | 4 | /** @type {HTMLOListElement} */ 5 | var tocTree; 6 | /** @type {HTMLHeadingElement[]} */ 7 | var headings; 8 | 9 | /** @type {HTMLAnchorElement} */ 10 | var currentTocLink; 11 | /** @type {IntersectionObserver} */ 12 | var intersectionObserver; 13 | 14 | /** @type {Set} */ 15 | var intersectingHeadings; 16 | 17 | function headingIntersect(entries) { 18 | if (!matchMedia('screen and (min-width: 55rem)').matches) { 19 | return; 20 | } 21 | entries.forEach(function (entry) { 22 | if (entry.isIntersecting) { 23 | intersectingHeadings.add(entry.target); 24 | } else { 25 | intersectingHeadings.delete(entry.target); 26 | } 27 | }); 28 | var firstIntersectingHeading = intersectingHeadings.values().next().value; 29 | var firstEntry = entries[0]; 30 | var intersectingHeading; 31 | if (firstIntersectingHeading) { 32 | intersectingHeading = firstIntersectingHeading; 33 | } else if ( 34 | firstEntry.boundingClientRect && 35 | firstEntry.boundingClientRect.y > 0 36 | ) { 37 | /* Scrolling upwards: Focus previous heading */ 38 | var index = Array.from(headings).findIndex(function (candidate) { 39 | return candidate === firstEntry.target; 40 | }); 41 | if (index > 0) { 42 | intersectingHeading = headings[index - 1]; 43 | } 44 | } 45 | if (intersectingHeading) { 46 | if (currentTocLink) { 47 | currentTocLink.classList.remove('active'); 48 | } 49 | var id = intersectingHeading.id; 50 | var tocLinks = Array.from(tocTree.querySelectorAll('a')); 51 | var link = tocLinks.find(function (linkCandidate) { 52 | return linkCandidate.hash === '#' + id; 53 | }); 54 | if (link) { 55 | link.classList.add('active'); 56 | link.scrollIntoView({ block: 'nearest' }); 57 | currentTocLink = link; 58 | } 59 | } 60 | } 61 | 62 | function installHighlightToc() { 63 | intersectingHeadings = new Set() 64 | tocTree = document.getElementById('toc-tree'); 65 | headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6'); 66 | 67 | intersectionObserver = new IntersectionObserver(headingIntersect, { 68 | root: null, 69 | rootMargin: '0px 0px -40% 0px', 70 | threshold: 0, 71 | }); 72 | 73 | Array.from(headings) 74 | .filter(function (heading) { 75 | return heading.id !== 'toc-heading'; 76 | }) 77 | .forEach(function (heading) { 78 | intersectionObserver.observe(heading); 79 | }); 80 | } 81 | 82 | if ( 83 | document.getElementById && 84 | document.querySelectorAll && 85 | window.IntersectionObserver && 86 | window.matchMedia && 87 | document.body.classList && 88 | document.body.scrollIntoView && 89 | Array.from && 90 | Array.prototype.find && 91 | Array.prototype.findIndex && 92 | Array.prototype.filter && 93 | Array.prototype.forEach && 94 | String.prototype.endsWith && 95 | window.Set 96 | ) { 97 | installHighlightToc(); 98 | } 99 | })(); 100 | -------------------------------------------------------------------------------- /assets/js/iframe-buttons.js: -------------------------------------------------------------------------------- 1 | (function () { 2 | 'use strict'; 3 | 4 | function installIframeButtons() { 5 | var loadIframeButtons = document.getElementsByClassName('load-iframe'); 6 | for (var i = 0, l = loadIframeButtons.length; i < l; i++) { 7 | var button = loadIframeButtons[i]; 8 | button.onclick = function (event) { 9 | var button = event.target; 10 | var scriptTemplate = button.parentNode.nextElementSibling; 11 | var iframeHTML = scriptTemplate.textContent; 12 | var container = document.createElement('div'); 13 | container.innerHTML = iframeHTML; 14 | scriptTemplate.parentNode.replaceChild(container, scriptTemplate); 15 | button.parentNode.removeChild(button); 16 | }; 17 | } 18 | } 19 | 20 | if ( 21 | document.getElementsByClassName && 22 | 'nextElementSibling' in document.body && 23 | document.createElement && 24 | document.body.replaceChild && 25 | document.body.removeChild 26 | ) { 27 | installIframeButtons(); 28 | } 29 | })(); 30 | -------------------------------------------------------------------------------- /assets/testing-angular.epub: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/molily/testing-angular/bb6e3a929c3de8875730afb75216e7e973ac4a7c/assets/testing-angular.epub -------------------------------------------------------------------------------- /debugging-tests.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Debugging tests 4 | description: How to debug Angular unit and integration tests 5 | --- 6 | 7 | # Debugging tests 8 | 9 | 17 | 18 | Writing tests is as arduous as writing implementation code. You will be stuck quite often and ask yourself why the test fails – and sometimes why the test passes when it should rather fail. 19 | 20 | The good news is that you can apply familiar debugging techniques to tests as well. 21 | 22 | ## Test focus 23 | 24 | Some tests require an extensive *Arrange* phase, the *Act* phase calls several methods or simulates complex user input. These tests are hard to debug. 25 | 26 | 27 | 28 | When locating an error, narrow down the scope gradually: Execute only one test, one suite, one spec, one expectation. 29 | 30 | Per default, Karma and Jasmine compile and run all specs again with every code change. This leads to a slow feedback cycle when you work on a particular spec. After a code change, it may take 10-20 seconds before you see the test result. Also one spec might interfere with another spec. 31 | 32 | The easiest way to narrow down the scope is to set a **focus** on a suite or spec. Let us assume you have a test suite with two specs: 33 | 34 | ```typescript 35 | describe('Example spec', () => { 36 | it('one spec', () => { /* … */ }); 37 | it('another spec', () => { /* … */ }); 38 | }); 39 | ``` 40 | 41 | 44 | 45 | If you want Jasmine to run only this test suite and skip all others, change `describe` to `fdescribe`: 46 | 47 | ```typescript 48 | fdescribe('Example spec', () => { 49 | it('one spec', () => { /* … */ }); 50 | it('another spec', () => { /* … */ }); 51 | }); 52 | ``` 53 | 54 | 57 | 58 | If you want Jasmine to run only one spec, change `it` to `fit`: 59 | 60 | ```typescript 61 | describe('Example spec', () => { 62 | fit('one spec', () => { /* … */ }); 63 | it('another spec', () => { /* … */ }); 64 | }); 65 | ``` 66 | 67 | This improves the developing experience tremendously. 68 | 69 | The Webpack module bundler still re-emits the whole bundle even if you have only changed one line of code and even if there is a test focus on one suite. 70 | 71 | 72 | 73 | In this case, you can instruct `ng test` to consider only the file you are currently working on. Webpack then includes all its dependencies, like the Angular framework, but not more. 74 | 75 | For example, to include only tests called `counter.component.spec.ts`, we call `ng test` with the `--include` option. 76 | 77 | ``` 78 | ng test --include **/counter.component.spec.ts 79 | ``` 80 | 81 | `**/counter.component.spec.ts` means all files called `counter.component.spec.ts` in any subdirectory. 82 | 83 | The bundling is now fast and the feedback is almost instant when we change implementation or test code. 84 | 85 | Keep in mind to remove the test focus before committing your code. There are several tools that prevent `fdescribe` and `fit` from being committed. 86 | 87 |
88 | - [Jasmine API reference: fdescribe](https://jasmine.github.io/api/edge/global.html#fdescribe) 89 | - [Jasmine API reference: fit](https://jasmine.github.io/api/edge/global.html#fit) 90 | - [Angular CLI reference: ng test](https://angular.io/cli/test) 91 | - [Tim Deschryver: Don't commit focused tests](https://timdeschryver.dev/blog/dont-commit-focused-tests) 92 |
93 | 94 | ## Developer tools 95 | 96 | The Jasmine test runner is just another web page made with HTML, CSS and JavaScript. This means you can debug it in the browser using the developer tools. 97 | 98 | 99 | 100 | Focus the browser window and open the developer tools. In Chrome, Firefox and Edge, you can use the F12 key. 101 | 102 | You can use the developer tools to: 103 | 104 | - Write debug output to the console using `console.log`, `console.debug` and friends. 105 | - Use the JavaScript debugger. You can either set breakpoints in the developer tools or place a `debugger` statement. 106 | - Inspect the DOM of rendered Components. 107 | 108 | ## Debug output and the JavaScript debugger 109 | 110 | The most primitive tool, `console.log`, is in fact invaluable when debugging tests. You can place debug output both in the test code and the implementation code. 111 | 112 | 115 | 116 | Use debug output to answer these questions: 117 | 118 | - Is the test, suite, spec run at all? 119 | - Does the test execution reach the log command? 120 | - Did the test call the class, method, function under test correctly? 121 | - Are callbacks called correctly? Do Promises complete or fail? Do Observables emit, complete or error? 122 | - For Component tests: 123 | - Is Input data passed correctly? 124 | - Are the lifecycle methods called correctly? 125 | 126 | 129 | 130 | Some people prefer to use `debugger` instead of console output. 131 | 132 | 133 | Jasmine test with debugger statement in the code under test 134 | 135 | 136 | While the debugger certainly gives you more control, it halts the JavaScript execution. It may disturb the processing of asynchronous JavaScript tasks and the order of execution. 137 | 138 | 139 | 140 | The `console` methods have their own pitfalls. For performance reasons, browsers do not write the output to the console synchronously, but asynchronously. 141 | 142 | If you output a complex object with `console.log(object)`, most browsers render an interactive representation of the object on the console. You can click on the object to inspect its properties. 143 | 144 | ```typescript 145 | const exampleObject = { name: 'Usagi Tsukino' }; 146 | console.log(exampleObject); 147 | ``` 148 | 149 | It is important to know that the rendering happens asynchronously. If you change the object shortly after, you might see the changed object, not the object at the time of the `console.log` call. 150 | 151 | ```typescript 152 | const exampleObject = { name: 'Usagi Tsukino' }; 153 | console.log(exampleObject); 154 | exampleObject.name = 'Sailor Moon'; 155 | ``` 156 | 157 | On the console, the object representation may show `name: 'Sailor Moon'` instead of `name: 'Usagi Tsukino'`. 158 | 159 | One way to prevent this confusion is to create a snapshot of the object. You convert the object to a JSON string: 160 | 161 | ```typescript 162 | const exampleObject = { name: 'Usagi Tsukino' }; 163 | console.log(JSON.stringify(exampleObject, null, ' ')); 164 | exampleObject.name = 'Sailor Moon'; 165 | ``` 166 | 167 | 168 | 169 | If you want an interactive representation on the console, create a copy of the object with `JSON.stringify` followed by `JSON.parse`: 170 | 171 | ```typescript 172 | const exampleObject = { name: 'Usagi Tsukino' }; 173 | console.log(JSON.parse(JSON.stringify(exampleObject))); 174 | exampleObject.name = 'Sailor Moon'; 175 | ``` 176 | 177 | Obviously, this only works for objects that can be serialized as JSON. 178 | 179 | ## Inspect the DOM 180 | 181 | In the next chapter, we will learn how to test Components. These tests will render the Component into the DOM of the Jasmine test runner page. This means you can briefly see the states of the rendered Component in the browser. 182 | 183 | 184 | DOM of the Component under test in the DOM inspector 185 | 186 | 187 | In the screenshot above, you see the rendered Component on the left side and the inspected DOM on the right side. 188 | 189 | 190 | 191 | The Component’s root element is rendered into the last element in the document, below the Jasmine reporter output. Make sure to set a focus on a single spec to see the rendered Component. 192 | 193 | The rendered Component is interactive. For example, you can click on buttons and the click handlers will be called. But as we will learn later, there is no automatic change detection in the testing environment. So you might not see the effect of the interaction. 194 | 195 | ## Jasmine debug runner 196 | 197 | The Karma page at [http://localhost:9876](http://localhost:9876) loads an iframe with the actual Jasmine instance, http://localhost:9876/context.html. This iframe complicates debugging because the developer tools operate on the topmost document per default. 198 | 199 | In the developer tools, you can select the iframe window context (Chrome is pictured): 200 | 201 | 202 | Developer tools: Select the context iframe 203 | 204 | 205 | This way you can access global objects and the DOM of the document where the tests run. 206 | 207 | 208 | 209 | Another helpful feature is Karma’s debug test runner. Click on the big “DEBUG” button on the top-right. Then a new tab opens with [http://localhost:9876/debug.html](http://localhost:9876/debug.html). 210 | 211 | 212 | Jasmine debug runner 213 | 214 | 215 | The debug test runner does not have an iframe, it loads Jasmine directly. Also it automatically logs spec runs on the shell. 216 | 217 | If you change the test or implementation code, the debug runner does not re-run the tests. You have to reload the page manually. 218 | 219 | 220 | -------------------------------------------------------------------------------- /example-applications.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Angular example applications with tests 4 | description: Fully-tested Angular projects used as example in this book 5 | --- 6 | 7 | # Example applications 8 | 9 | 15 | 16 | In this guide, we will explore the different aspects of testing Angular applications by looking at two examples. 17 | 18 | ## The counter Component 19 | 20 |
21 | - [Counter Component: Source code](https://github.com/9elements/angular-workshop) 22 | - [Counter Component: Run the app](https://9elements.github.io/angular-workshop/) 23 |
24 | 25 | 28 | 29 | 34 | 35 | The counter is a reusable Component that increments, decrements and resets a number using buttons and input fields. 36 | 37 | 38 | 39 | For intermediate Angular developers, this might look trivial. That is intentional. This guide assumes that you know Angular basics and that you are able to build a counter Component, but struggle testing the ins and outs. 40 | 41 | The goals of this example are: 42 | 43 | - **Simplicity**: Quickly grasp what the Component is supposed to do. 44 | - **Cover core Angular features**: Reusable Components with state, Inputs, Outputs, templates, event handling. 45 | - **Scalability**: Starting point for more complex application architectures. 46 | 47 | 48 | 49 | The counter comes in three flavors with different state management solutions: 50 | 51 | 1. An independent, self-sufficient counter Component that holds its own state. 52 | 2. A counter that is connected to a Service using dependency injection. It shares its state with other counters and changes it by calling Service methods. 53 | 3. A counter that is connected to a central NgRx Store. (NgRx is a popular state management library.) The counter changes the state indirectly by dispatching NgRx Actions. 54 | 55 | While the counter seems easy to implement, it already offers valuable challenges from a testing perspective. 56 | 57 | ## The Flickr photo search 58 | 59 |
60 | - [Flickr photo search: Source code](https://github.com/9elements/angular-flickr-search) 61 | - [Flickr photo search: Run the app](https://9elements.github.io/angular-flickr-search/) 62 |
63 | 64 | 67 | 68 | 73 | 74 | This application allows you to search for photos on Flickr, the popular photo hosting site. 75 | 76 | 77 | 78 | First, you enter a search term and start the search. The Flickr search API is queried. Second, the search results with thumbnails are rendered. Third, you can select a search result to see the photo details. 79 | 80 | This application is straight-forward and relatively simple to implement. Still it raises important questions: 81 | 82 | - **App structure**: How to split responsibilities into Components and how to model dependencies. 83 | - **API communication**: How to fetch data by making HTTP requests and update the user interface. 84 | - **State management**: Where to hold the state, how to pass it down in the Component tree, how to alter it. 85 | 86 | The Flickr search comes in two flavors using different state management solutions: 87 | 88 | 89 | 90 | 1. The state is managed in the top-level Component, passed down in the Component tree and changed using Outputs. 91 | 2. The state is managed by an NgRx Store. Components are connected to the store to pull state and dispatch Actions. The state is changed in a Reducer. The side effects of an Action are handled by NgRx Effects. 92 | 93 | Once you are able to write automatic tests for this example application, you will be able to test most features of a typical Angular application. 94 | 95 | 96 | -------------------------------------------------------------------------------- /faking-dependencies.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Faking dependencies (Mocking) 4 | description: How to mock dependencies to test Components and Services in isolation 5 | --- 6 | 7 | # Faking dependencies 8 | 9 | 17 | 18 | When testing a piece of code, you need to decide between an [integration test](../testing-principles/#integration-tests) and a [unit test](../testing-principles/#unit-tests). To recap, the integration test includes (“integrates”) the dependencies. In contrast, the unit test replaces the dependencies with fakes in order to isolate the code under test. 19 | 20 | 21 | 22 | These replacements are also called *test doubles*, *stubs* or *mocks*. Replacing a dependency is called *stubbing* or *mocking*. 23 | 24 | Since these terms are used inconsistently and their difference is subtle, **this guide uses the term “fake” and “faking”** for any dependency substitution. 25 | 26 | 27 | 28 | Creating and injecting fake dependencies is essential for unit tests. This technique is double-edged – powerful and dangerous at the same time. Since we will create many fakes throughout this guide, we need to set up **rules for faking dependencies** to apply the technique safely. 29 | 30 | ## Equivalence of fake and original 31 | 32 | A fake implementation must have the same shape as the original. If the dependency is a function, the fake must have the same signature, meaning the same parameters and the same return value. If the dependency is an object, the fake must have the same public API, meaning the same public methods and properties. 33 | 34 | 35 | 36 | The fake does not need to be complete, but sufficient enough to act as a replacement. The fake needs to be **equivalent to the original** as far as the code under test is concerned, not fully equal to the original. 37 | 38 | Imagine a fake building on a movie set. The outer shape needs to be indistinguishable from an original building. But behind the authentic facade, there is only a wooden scaffold. The building is an empty shell. 39 | 40 | The biggest danger of creating a fake is that it does not properly mimic the original. Even if the fake resembles the original at the time of writing the code, it might easily get out of sync later when the original is changed. 41 | 42 | When the original dependency changes its public API, dependent code needs to be adapted. Also, the fake needs to be aligned. When the fake is outdated, the unit test becomes a fantasy world where everything magically works. The test passes but in fact the code under test is broken. 43 | 44 | 45 | 46 | How can we ensure that the fake is up-to-date with the original? How can we ensure the equivalence of original and fake in the long run and prevent any possible divergence? 47 | 48 | We can use TypeScript to **enforce that the fake has a matching type**. The fake needs to be strictly typed. The fake’s type needs to be a subset of the original’s type. 49 | 50 | 51 | 52 | Then, TypeScript assures the equivalence. The compiler reminds us to update the implementation and the fake. The TypeScript code simply does not compile if we forget that. We will learn how to declare matching types in the upcoming examples. 53 | 54 | ## Effective faking 55 | 56 | The original dependency code has side effects that need to be suppressed during testing. The fake needs to *effectively* prevent the original code from being executed. Strange errors may happen if a mix of fake and original code is executed. 57 | 58 | 59 | 60 | In some faking approaches, the fake inherits from the original. Only those properties and methods are overwritten that are currently used by the code under test. 61 | 62 | This is dangerous since we may forget to overwrite methods. When the code under test changes, the test may accidentally call original methods of the dependency. 63 | 64 | This guide will present thorough faking techniques that do not allow a slip. They imitate the original code while shielding the original from calls. 65 | 66 | ## Faking functions with Jasmine spies 67 | 68 | Jasmine provides simple yet powerful patterns to create fake implementations. The most basic pattern is the **Jasmine spy** for replacing a function dependency. 69 | 70 | 71 | 72 | In its simplest form, a spy is a function that records its calls. For each call, it records the function parameters. Using this record, we later assert that the spy has been called with particular input values. 73 | 74 | For example, we declare in a spec: “Expect that the spy has been called two times with the values `mickey` and `minnie`, respectively.” 75 | 76 | Like every other function, a spy can have a meaningful return value. In the simple case, this is a fixed value. The spy will always return the same value, regardless of the input parameters. In a more complex case, the return value originates from an underlying fake function. 77 | 78 | 81 | 82 | A standalone spy is created by calling `jasmine.createSpy`: 83 | 84 | ```typescript 85 | const spy = jasmine.createSpy('name'); 86 | ``` 87 | 88 | `createSpy` expects one parameter, an optional name. It is recommended to pass a name that describes the original. The name will be used in error messages when you make expectations against the spy. 89 | 90 | Assume we have class `TodoService` responsible for fetching a to-do list from the server. The class uses the [Fetch API](https://developer.mozilla.org/de/docs/Web/API/Fetch_API) to make an HTTP request. (This is a plain TypeScript example. It is uncommon to use `fetch` directly in an Angular app.) 91 | 92 | ```typescript 93 | class TodoService { 94 | constructor( 95 | // Bind `fetch` to `window` to ensure that `window` is the `this` context 96 | private fetch = window.fetch.bind(window) 97 | ) {} 98 | 99 | public async getTodos(): Promise { 100 | const response = await this.fetch('/todos'); 101 | if (!response.ok) { 102 | throw new Error( 103 | `HTTP error: ${response.status} ${response.statusText}` 104 | ); 105 | } 106 | return await response.json(); 107 | } 108 | } 109 | ``` 110 | 111 | 112 | 113 | The `TodoService` uses the **constructor injection** pattern. The `fetch` dependency can be injected via an optional constructor parameter. In production code, this parameter is empty and defaults to the original `window.fetch`. In the test, a fake dependency is passed to the constructor. 114 | 115 | The `fetch` parameter, whether original or fake, is saved as an instance property `this.fetch`. Eventually, the public method `getTodos` uses it to make an HTTP request. 116 | 117 | In our unit test, we do not want the Service to make any HTTP requests. We pass in a Jasmine spy as replacement for `window.fetch`. 118 | 119 | ```typescript 120 | // Fake todos and response object 121 | const todos = [ 122 | 'shop groceries', 123 | 'mow the lawn', 124 | 'take the cat to the vet' 125 | ]; 126 | const okResponse = new Response(JSON.stringify(todos), { 127 | status: 200, 128 | statusText: 'OK', 129 | }); 130 | 131 | describe('TodoService', () => { 132 | it('gets the to-dos', async () => { 133 | // Arrange 134 | const fetchSpy = jasmine.createSpy('fetch') 135 | .and.returnValue(okResponse); 136 | const todoService = new TodoService(fetchSpy); 137 | 138 | // Act 139 | const actualTodos = await todoService.getTodos(); 140 | 141 | // Assert 142 | expect(actualTodos).toEqual(todos); 143 | expect(fetchSpy).toHaveBeenCalledWith('/todos'); 144 | }); 145 | }); 146 | ``` 147 | 148 | There is a lot to unpack in this example. Let us start with the fake data before the `describe` block: 149 | 150 | ```typescript 151 | const todos = [ 152 | 'shop groceries', 153 | 'mow the lawn', 154 | 'take the cat to the vet' 155 | ]; 156 | const okResponse = new Response(JSON.stringify(todos), { 157 | status: 200, 158 | statusText: 'OK', 159 | }); 160 | ``` 161 | 162 | First, we define the fake data we want the `fetch` spy to return. Essentially, this is an array of strings. 163 | 164 | 165 | 166 | The original `fetch` function returns a `Response` object. We create one using the built-in `Response` constructor. The original server response is a string before it is parsed as JSON. So we need to serialize the array into a string before passing it to the `Response` constructor. (These `fetch` details are not relevant to grasp the spy example.) 167 | 168 | Then, we declare a test suite using `describe`: 169 | 170 | ```typescript 171 | describe('TodoService', () => { 172 | /* … */ 173 | }); 174 | ``` 175 | 176 | The suite contains one spec that tests the `getTodos` method: 177 | 178 | ```typescript 179 | it('gets the to-dos', async () => { 180 | /* … */ 181 | }); 182 | ``` 183 | 184 | The spec starts with *Arrange* code: 185 | 186 | ```typescript 187 | // Arrange 188 | const fetchSpy = jasmine.createSpy('fetch') 189 | .and.returnValue(okResponse); 190 | const todoService = new TodoService(fetchSpy); 191 | ``` 192 | 193 | Here, we create a spy. With `.and.returnValue(…)`, we set a fixed return value: the successful response. 194 | 195 | 196 | 197 | We also create an instance of `TodoService`, the class under test. We pass the spy into the constructor. This is a form of manual dependency injection. 198 | 199 | In the *Act* phase, we call the method under test: 200 | 201 | ```typescript 202 | const actualTodos = await todoService.getTodos(); 203 | ``` 204 | 205 | `getTodos` returns a Promise. We use an `async` function together with `await` to access the return value easily. Jasmine deals with async functions just fine and waits for them to complete. 206 | 207 | In the *Assert* phase, we create two expectations: 208 | 209 | ```typescript 210 | expect(actualTodos).toEqual(todos); 211 | expect(fetchSpy).toHaveBeenCalledWith('/todos'); 212 | ``` 213 | 214 | 215 | 216 | First, we verify the return value. We compare the actual data (`actualTodos`) with the fake data the spy returns (`todos`). If they are equal, we have proven that `getTodos` parsed the response as JSON and returned the result. (Since there is no other way `getTodos` could access the fake data, we can deduce that the spy has been called.) 217 | 218 | 219 | 220 | Second, we verify that the `fetch` spy has been called *with the correct parameter*, the API endpoint URL. Jasmine offers several matchers for making expectations on spies. The example uses `toHaveBeenCalledWith` to assert that the spy has been called with the parameter `'/todos'`. 221 | 222 | Both expectations are necessary to guarantee that `getTodos` works correctly. 223 | 224 | 225 | 226 | After having written the first spec for `getTodos`, we need to ask ourselves: Does the test fully cover its behavior? We have tested the success case, also called *happy path*, but the error case, also called *unhappy path*, is yet to be tested. In particular, this error handling code: 227 | 228 | ```typescript 229 | if (!response.ok) { 230 | throw new Error( 231 | `HTTP error: ${response.status} ${response.statusText}` 232 | ); 233 | } 234 | ``` 235 | 236 | When the server response is not “ok”, we throw an error. “Ok” means the HTTP response status code is 200-299. Examples of “not ok” are “403 Forbidden”, “404 Not Found” and “500 Internal Server Error”. Throwing an error rejects the Promise so the caller of `getTodos` knows that fetching the to-dos failed. 237 | 238 | The fake `okResponse` mimics the success case. For the error case, we need to define another fake `Response`. Let us call it `errorResponse` with the notorious HTTP status 404 Not Found: 239 | 240 | ```typescript 241 | const errorResponse = new Response('Not Found', { 242 | status: 404, 243 | statusText: 'Not Found', 244 | }); 245 | ``` 246 | 247 | Assuming the server does not return JSON in the error case, the response body is simply the string `'Not Found'`. 248 | 249 | Now we add a second spec for the error case: 250 | 251 | ```typescript 252 | describe('TodoService', () => { 253 | /* … */ 254 | it('handles an HTTP error when getting the to-dos', async () => { 255 | // Arrange 256 | const fetchSpy = jasmine.createSpy('fetch') 257 | .and.returnValue(errorResponse); 258 | const todoService = new TodoService(fetchSpy); 259 | 260 | // Act 261 | let error; 262 | try { 263 | await todoService.getTodos(); 264 | } catch (e) { 265 | error = e; 266 | } 267 | 268 | // Assert 269 | expect(error).toEqual(new Error('HTTP error: 404 Not Found')); 270 | expect(fetchSpy).toHaveBeenCalledWith('/todos'); 271 | }); 272 | }); 273 | ``` 274 | 275 | In the *Arrange* phase, we inject a spy that returns the error response. 276 | 277 | 278 | 279 | In the *Act* phase, we call the method under test but anticipate that it throws an error. In Jasmine, there are several ways to test whether a Promise has been rejected with an error. The example above wraps the `getTodos` call in a `try/catch` statement and saves the error. Most likely, this is how implementation code would handle the error. 280 | 281 | In the *Assert* phase, we make two expectations again. Instead of verifying the return value, we make sure the caught error is an `Error` instance with a useful error message. Finally, we verify that the spy has been called with the right value, just like in the spec for the success case. 282 | 283 | Again, this is a plain TypeScript example to illustrate the usage of spies. Usually, an Angular Service does not use `fetch` directly but uses `HttpClient` instead. We will get to know testing this later (see [Testing a Service that sends HTTP requests](../testing-services/#testing-a-service-that-sends-http-requests)). 284 | 285 |
286 | - [TodoService: Implementation and test code](https://github.com/9elements/angular-workshop/blob/main/src/app/services/todos-service.spec.ts) 287 | - [Jasmine reference: Spies](https://jasmine.github.io/api/edge/Spy.html) 288 |
289 | 290 | ## Spying on existing methods 291 | 292 | We have used `jasmine.createSpy('name')` to create a standalone spy and have injected it into the constructor. Explicit constructor injection is straight-forward and used extensively in Angular code. 293 | 294 | 295 | 296 | Sometimes, there is already an object whose method we need to spy on. This is especially helpful if the code uses global methods from the browser environment, like `window.fetch` in the example above. 297 | 298 | For this purpose, we can use the `spyOn` method: 299 | 300 | ```typescript 301 | spyOn(window, 'fetch'); 302 | ``` 303 | 304 | 305 | 306 | This installs a spy on the global `fetch` method. Under the hood, Jasmine saves the original `window.fetch` function for later and overwrites `window.fetch` with a spy. Once the spec is completed, Jasmine automatically restores the original function. 307 | 308 | `spyOn` returns the created spy, enabling us to set a return value, like we have learned above. 309 | 310 | ```typescript 311 | spyOn(window, 'fetch') 312 | .and.returnValue(okResponse); 313 | ``` 314 | 315 | We can create a version of `TodoService` that does not rely on construction injection, but uses `fetch` directly: 316 | 317 | ```typescript 318 | class TodoService { 319 | public async getTodos(): Promise { 320 | const response = await fetch('/todos'); 321 | if (!response.ok) { 322 | throw new Error( 323 | `HTTP error: ${response.status} ${response.statusText}` 324 | ); 325 | } 326 | return await response.json(); 327 | } 328 | } 329 | ``` 330 | 331 | The test suite then uses `spyOn` to catch all calls to `window.fetch`: 332 | 333 | ```typescript 334 | // Fake todos and response object 335 | const todos = [ 336 | 'shop groceries', 337 | 'mow the lawn', 338 | 'take the cat to the vet' 339 | ]; 340 | const okResponse = new Response(JSON.stringify(todos), { 341 | status: 200, 342 | statusText: 'OK', 343 | }); 344 | 345 | describe('TodoService', () => { 346 | it('gets the to-dos', async () => { 347 | // Arrange 348 | spyOn(window, 'fetch') 349 | .and.returnValue(okResponse); 350 | const todoService = new TodoService(); 351 | 352 | // Act 353 | const actualTodos = await todoService.getTodos(); 354 | 355 | // Assert 356 | expect(actualTodos).toEqual(todos); 357 | expect(window.fetch).toHaveBeenCalledWith('/todos'); 358 | }); 359 | }); 360 | ``` 361 | 362 | Not much has changed here. We spy on `fetch` and make it return `okResponse`. Since `window.fetch` is overwritten with a spy, we make the expectation against it to verify that it has been called. 363 | 364 | Creating standalone spies and spying on existing methods are not mutually exclusive. Both will be used frequently when testing Angular applications, and both work well with dependencies injected into the constructor. 365 | 366 |
367 | - [Jasmine reference: spyOn](https://jasmine.github.io/api/edge/global.html#spyOn) 368 |
369 | 370 | 371 | -------------------------------------------------------------------------------- /index-of-example-applications.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Index of example applications 4 | description: Angular example projects with tests used across this book 5 | --- 6 | 7 | # Index of example applications 8 | 9 | All example applications are repositories on GitHub: 10 | 11 |
12 | - [Counter Component](https://github.com/9elements/angular-workshop) 13 | - [Flickr photo search](https://github.com/9elements/angular-flickr-search) 14 | - [Sign-up form](https://github.com/molily/angular-form-testing) 15 | - [TranslatePipe](https://github.com/molily/translate-pipe) 16 | - [ThresholdWarningDirective](https://github.com/molily/threshold-warning-directive) 17 | - [PaginateDirective](https://github.com/molily/paginate-directive) 18 |
19 | 20 | 21 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | --- 2 | layout: book 3 | title: Testing Angular – A Guide to Robust Angular Applications. 4 | append_site_title: false 5 | --- 6 | 7 | {% include symbols.html %} 8 | 9 |
10 | 11 | 15 | 16 |
17 | 18 |

19 | 20 | 21 | 22 | 23 | 24 | Photo of flying probes testing a printed circuit board. 28 | 29 | 30 | 31 | 32 | Flying probes testing a printed circuit board. Photo by genkur from iStock. 33 | 34 |

35 | 36 |

37 | {{ site.title }}
38 | {{ site.subtitle }}
39 | A free online book and e-book 40 |

41 | 42 |

The Angular framework is a mature and comprehensive solution for enterprise-ready applications based on web technologies. At Angular’s core lies the ability to test all application parts in an automated way. How do we take advantage of Angular’s testability?

43 | 44 |

This guide explains the principles of automated testing as well as the practice of testing Angular web applications. It empowers you and your team to write effective tests on a daily basis.

45 | 46 |

In this book, you learn how to set up your own testing conventions, write your own testing helpers and apply proven testing libraries. The book covers different tests that complement each other: unit tests, integration tests and end-to-end tests.

47 | 48 |

With a strong focus on testing Angular Components, this guide teaches you to write realistic specs that describe and verify a Component’s behavior. It demonstrates how to properly mock dependencies like Services to test a Component in isolation. The guide introduces the Spectator and ng-mocks libraries, two powerful testing libraries.

49 | 50 |

Apart from Components, the book illustrates how to test the other application parts: Services, Pipes, Directives as well as Modules. Last but not least, it covers end-to-end tests with Cypress.

51 |
52 | 53 | 54 | 55 | 58 | 59 | 64 | 65 | {% include footer.html %} 66 | -------------------------------------------------------------------------------- /introduction.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Introduction 4 | description: Why is automated testing so controversial and contested? 5 | --- 6 | 7 | # Introduction 8 | 9 | 17 | 18 | Most web developers come across automated tests in their career. They fancy the idea of writing code to scrutinize a web application and put it to an acid test. As web developers, as business people, we want to know whether the site works for the user, our customers. 19 | 20 | Does the site allow the user to complete their tasks? Is the site still functional after new features have been introduced or internals have been refactored? How does the site react to usage errors or system failure? Testing gives answers to these questions. 21 | 22 | I believe the benefits of automated testing are easy to grasp. Developers want to sleep well and be confident that their application works correctly. Moreover, testing helps developers to write better software. Software that is more robust, better to understand and easier to maintain. 23 | 24 | In stark contrast, I have met only few web developers with a steady testing practice. Only few find it *easy*, let alone *enjoy* writing tests. This task is seen as a chore or nuisance. 25 | 26 | Often individual developers are blamed for the lack of tests. The claim that developers are just too ignorant or lazy to write tests is simplistic and downright toxic. If testing has an indisputable value, we need to examine why developers avoid it while being convinced of the benefits. Testing should be easy, straight-forward and commonplace. 27 | 28 | If you are struggling with writing tests, it is not your fault or deficit. We are all struggling because testing software is inherently complicated and difficult. 29 | 30 | First, writing automated tests requires a different mindset than writing the implementation code. Implementing a feature means building a structure – testing means trying to knock it over. 31 | 32 | You try to find weaknesses and loopholes in your own work. You think through all possible cases and pester your code with “What if?” questions. What seems frustrating at first sight is an invaluable strategy to improve your code. 33 | 34 | Second, testing has a steep learning curve. If testing can be seen as a tool, it is not a like a screwdriver or power drill. Rather, it compares to a tractor or excavator. It takes training to operate these machines. And it takes experience to apply them accurately and safely. 35 | 36 | This is meant to encourage you. Getting started with testing is hard, but it gets easier and easier with more practice. The goal of this guide is to empower you to write tests on a daily basis that cover the important features of your Angular application. 37 | 38 | 39 | -------------------------------------------------------------------------------- /license.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: License 4 | description: Copyright and contact information for this book 5 | --- 6 | 7 | # License 8 | 9 | License: Creative Commons Attribution-ShareAlike (CC BY-SA 4.0) 10 | 11 | The example code is released into the public domain. See [Unlicense](https://unlicense.org/). 12 | 13 | The [Flickr search example application](https://github.com/9elements/angular-flickr-search) uses the [Flickr API](https://www.flickr.com/services/api/) but is not endorsed or certified by Flickr, Inc. or SmugMug, Inc. Flickr is a trademark of Flickr, Inc. The displayed photos are property of their respective owners. 14 | 15 | Online book cover photo: Flying probes testing a printed circuit board by genkur, [licensed from iStock](https://www.istockphoto.com/photo/printed-circuit-board-during-a-flying-probe-test-gm1144549508-307752215). 16 | 17 | E-book cover and favicon: [Official Angular logo](https://angular.io/presskit) by Google, licensed under [Creative Commons Attribution (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). 18 | 19 | Legal notice: Impressum und Datenschutz 20 | -------------------------------------------------------------------------------- /localhost.crt: -------------------------------------------------------------------------------- 1 | -----BEGIN CERTIFICATE----- 2 | MIIDvjCCAqagAwIBAgIJAPPZEZ134kpJMA0GCSqGSIb3DQEBCwUAMIGKMQswCQYD 3 | VQQGEwJVUzELMAkGA1UECAwCS1MxDzANBgNVBAcMBk9sYXRoZTELMAkGA1UECgwC 4 | SVQxFjAUBgNVBAsMDUlUIERlcGFydG1lbnQxJDAiBgkqhkiG9w0BCQEWFXdlYm1h 5 | c3RlckBleGFtcGxlLmNvbTESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTIxMDQzMDE3 6 | MDA1MloXDTIyMDQzMDE3MDA1MlowgYoxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJL 7 | UzEPMA0GA1UEBwwGT2xhdGhlMQswCQYDVQQKDAJJVDEWMBQGA1UECwwNSVQgRGVw 8 | YXJ0bWVudDEkMCIGCSqGSIb3DQEJARYVd2VibWFzdGVyQGV4YW1wbGUuY29tMRIw 9 | EAYDVQQDDAlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB 10 | AQCfH9gpwtANrB/XRrF250GRWrFWOuIMq8xNgs1FUQlfmdPOmAbFtBOI7sLL0oj+ 11 | A4uyulF5wruRopsZbCumo3d8M9IpsgXBelqs31MDfxtsC2TSDUDwNPHGHZfKpQtC 12 | nMj8R9+Dt/degpZDaOM/tu3EBWnyEIboNT0mEmikOE+qyZFKs6dPssu9LY1DHQK2 13 | ptF133/69fy/jqYh8gCJMgUovBL8AWNr0zAC6LMidH9MuAqdxeTV0+oPZUQuqe5W 14 | JghdqxITbggj47T4Aa+Wi/LGBN/Rx93iZIBQAKvz5PcK6v7cvCGqxQaEjyGD01L0 15 | SJmvaD/7QuevayM9NZMlkOUTAgMBAAGjJTAjMCEGA1UdEQQaMBiCCyoubG9jYWxo 16 | b3N0gglsb2NhbGhvc3QwDQYJKoZIhvcNAQELBQADggEBAF0FZaSwDGzDAJrp/zTx 17 | xAIm3CG7cPGkD4RZuZBixYx51uqdBt59r4igNJeleqwnLBCESOsYJCzhQtVaFkWV 18 | 03a9rA8VnH6rzj0PC1zv3+7Vi45i/q+5RTA+FdWKsN6UF8mTf37jnIevnI9xU4mW 19 | a2wG+QitWq5gA+OFn/aD3VWVL48/oM1n6/fVxfmm7FtiIJEdQt872ZONoQhcgpJm 20 | fK4lvtKpVp3szHMdYQ6l5DCl9WS2du4M6z5CpL9XFM26CRzleN7tyZo6l3BiY+oW 21 | y+flQQTTGR+g1PFPKjFhdmhPOxF5efGgGgi8zbi6s4HAftzRaU0da4e6l1SyrW0y 22 | fQ8= 23 | -----END CERTIFICATE----- 24 | -------------------------------------------------------------------------------- /localhost.key: -------------------------------------------------------------------------------- 1 | -----BEGIN PRIVATE KEY----- 2 | MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCfH9gpwtANrB/X 3 | RrF250GRWrFWOuIMq8xNgs1FUQlfmdPOmAbFtBOI7sLL0oj+A4uyulF5wruRopsZ 4 | bCumo3d8M9IpsgXBelqs31MDfxtsC2TSDUDwNPHGHZfKpQtCnMj8R9+Dt/degpZD 5 | aOM/tu3EBWnyEIboNT0mEmikOE+qyZFKs6dPssu9LY1DHQK2ptF133/69fy/jqYh 6 | 8gCJMgUovBL8AWNr0zAC6LMidH9MuAqdxeTV0+oPZUQuqe5WJghdqxITbggj47T4 7 | Aa+Wi/LGBN/Rx93iZIBQAKvz5PcK6v7cvCGqxQaEjyGD01L0SJmvaD/7QuevayM9 8 | NZMlkOUTAgMBAAECggEBAIhxIsY0QHfoxmiuOk9NXiCH1pWs6dWZnhY8eUzdfp8V 9 | 5NM58lyl2zZIHInu3f6JBclcD67LNlBbUIjNAuThN/ws5yFPf7X19zhSSfkujVHo 10 | tyuRp8QQcdvB1j0xpeUZURFZg6OLJDZK3ROyJWGltlylk8G3QCZuOB+kG0vs6Qr0 11 | b0ZlmBfU3EehKDqgo0QbNAwOHQowNhyBsTSZPcgvD3uCXoAM4Hkfw8pDIwIY8Gz5 12 | sG+ACjywyQ6yG40l/0XYvgl5Bh6URItLp6X7nPCNkNeyIkJV6HMXvJiZrXcgPwim 13 | ILEjguN9kOiXt/AiULmtmrZ9zoBzX04j8EhbuguhoyECgYEAzkAMPpZ73RTwkuYX 14 | iPiBVJTZ3LGBN2h/XO5Q+ODhYrRP3OV2eJFBjch/z4DqiP8RS8zUxd5GX4bDAA/q 15 | GE8azC79wSS+040iOaDF7a1P+Wh4QQ/7XE3NDQTa2xJAbP0PZ9rvlnAkrVn2cny6 16 | Fk1TXYMM8FWJhRzCzK051QDF74MCgYEAxYHHLDzAj1fpl/NRt83svjRiMofgFunP 17 | HO3q8AtGt/kBBfmNyiGTTSqhLAW+TZ2dWr9tmTLX7hyUY4Ln0FMc1pxHcko+tIZa 18 | 1zI+37L7+vHsloANWwpUT9YHBkqw2ixf8O/uX5UGYc2SzyUnsT9SZ1iOlYPQJ6Yb 19 | 1V2Ay5lnLzECgYAXup6uBLozcVlMTVSf2Zdnl8iI75MiQM+GbZS7TYQgywX1MCE1 20 | NeEI4uxxfy98m3vt8J76NNx72RFOTIZuTYuTukRPmF6sECzD3I9pDOuKkk5jjecp 21 | c3oH6WsUkUEASQ0gsbum3zgZCaSk/1yZfEP/Gji+3dh4jBqNWdCxhOlA6QKBgQC7 22 | 7Girgb6iZT6A8uY9IjVxIPySIdCpXJxRZVsWPVRzdfxwR+uOePXkBXzHG0vgI+j1 23 | 0JCipMrp582VBZg2Eu6skJQ2fcg+Elxax5clV/MD6a534K1Ug3aHZBjY9rZhULmU 24 | 0WYZEf25j1VxvWOP9bUdWhiI0Jt9LkLreAU1M+gG8QKBgBBhJ3ARo372JjOAqniV 25 | EVcQW2v1sMGZ8Qa2P4D8oBOW2hjHzyMwsjgzFzr27M48TWZ1TmrtBOdZk0SismbI 26 | Gbz3iFROMgVo8/8wVaXGDprvoCJs5zM0N9HudzmFHVM8VgKPwbPI6JV0JkURC2qF 27 | HsGxhC/iwRCoHJAXZclkodJi 28 | -----END PRIVATE KEY----- 29 | -------------------------------------------------------------------------------- /measuring-code-coverage.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Measuring code coverage 4 | description: How to measure test coverage of Angular applications 5 | --- 6 | 7 | # Measuring code coverage 8 | 9 | 17 | 18 | Code coverage, also called test coverage, tells you which parts of your code are executed by running the unit and integration tests. Code coverage is typically expressed as percent values, for example, 79% statements, 53% branches, 74% functions, 78% lines. 19 | 20 | Statements are, broadly speaking, control structures like `if` and `for` as well as expressions separated by semicolon. Branches refers to the two branches of `if (…) {…} else {…}` and `… ? … : …` conditions. Functions and lines are self-explanatory. 21 | 22 | ## Coverage report 23 | 24 | In Angular’s Karma and Jasmine setup, [Istanbul](https://istanbul.js.org/) is used for measuring test coverage. Istanbul rewrites the code under test to record whether a statement, branch, function and line was called. Then it produces a comprehensive test report. 25 | 26 | To activate Istanbul when running the tests, add the `--code-coverage` parameter: 27 | 28 | ``` 29 | ng test --code-coverage 30 | ``` 31 | 32 | After the tests have completed, Istanbul saves the report in the `coverage` directory located in the Angular project directory. 33 | 34 | The report is a bunch of HTML files you can open with a browser. Start by opening `coverage/index.html` in the browser of your choice. 35 | 36 | The report for the Flickr search example looks like this: 37 | 38 | 39 | Code coverage report 40 | 41 | 42 | Istanbul creates an HTML page for every directory and every file. By following the links, you can descend to reports for the individual files. 43 | 44 | For example, the coverage report for [photo-item.component.ts](https://github.com/9elements/angular-flickr-search/blob/main/src/app/components/photo-item/photo-item.component.ts) of the Flickr search: 45 | 46 | 47 | Code coverage report for photo-item.component.ts. All statements, functions and lines are covered. There is one condition with two branches, one of which is not covered. 48 | 49 | 50 | The report renders the source code annotated with the information how many times a line was called. In the example above, the code is fully covered except for an irrelevant `else` branch, marked with an “E”. 51 | 52 | The spec `it('focusses a photo on click', () => {…})` clicks on the photo item to test whether the `focusPhoto` Output emits. Let us disable the spec on purpose to see the impact. 53 | 54 | 55 | Code coverage report for photo-item.component.ts. The method handleClick is not called by the test. 56 | 57 | 58 | You can tell from the coverage report above that the `handleClick` method is never called. A key Component behavior is untested. 59 | 60 | ## How to use the coverage report 61 | 62 | Now that we know how to generate the report, what should we do with it? 63 | 64 | In the chapter [The right amount of testing](../testing-principles/#the-right-amount-of-testing), we have identified code coverage as a useful, but flawed metric. As a quantitative measure, code coverage cannot assess the quality of your tests. 65 | 66 | Software testing is not a competition. We should not try to reach a particular score just for the sake of it. For what purpose are we measuring code coverage then? 67 | 68 | 69 | 70 | The coverage report is a valuable tool you should use while writing tests. It *reveals code behavior that is not yet tested*. The report not only guides your testing, it also deepens your understanding of how your tests work. 71 | 72 | Whatever your current coverage score is, use the reporting to monitor and improve your testing practice. As described in [Tailoring your testing approach](../testing-principles/#tailoring-your-testing-approach), testing should be part of the development routine. New features should include tests, bug fixes should include a test as proof and to prevent regressions. 73 | 74 | 75 | 76 | Writing new code and changing existing code should not lower the coverage score, but gradually increase it. This means if your existing tests cover 75% lines of code, new code needs to be at least 75% covered. Otherwise the score slowly deteriorates. 77 | 78 | It is common practice to run the unit and integration tests in a continuous integration environment and measure the code coverage. To enforce a certain coverage score and to prevent decline, you can configure **thresholds** in the [Karma configuration](../angular-testing-principles/#configuring-karma-and-jasmine). 79 | 80 | In `karma.conf.js`, you can add global thresholds for statements, branches, functions and lines. 81 | 82 | ``` 83 | coverageReporter: { 84 | /* … */ 85 | check: { 86 | global: { 87 | statements: 75, 88 | branches: 75, 89 | functions: 75, 90 | lines: 75, 91 | }, 92 | }, 93 | }, 94 | ``` 95 | 96 | In the configuration above, all values are set to 75%. If the coverage drops below that number, the test execution fails even if all specs succeeded. 97 | 98 | 99 | 100 | When new code is added to the project with a test coverage better than average, you can raise the thresholds slowly but steadily – for example, from `75` to `75.1`, `75.2`, `75.3` and so on. Soon these small improvements add up. 101 | 102 | Test coverage should not be a pointless competition that puts developers under pressure and shames those that do not meet an arbitrary mark. Measuring coverage is a tool you should use for your benefit. Keep in mind that writing meaningful, spot-on tests does not necessarily increase the coverage score. 103 | 104 | For beginners and experts alike, the coverage report helps to set up, debug and improve their tests. For experienced developers, the score helps to keep up a steady testing practice. 105 | 106 |
107 | - [karma-coverage Configuration](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md) 108 |
109 | 110 | 111 | -------------------------------------------------------------------------------- /offline.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Offline 8 | 29 | 30 | 31 |
32 |

🪐

33 |

Offline

34 |

You are currently offline and the page you requested is not cached.

35 |

Please try again with an internet connection. Thanks!

36 |
37 | 38 | 39 | -------------------------------------------------------------------------------- /references.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: References 4 | description: Recommended books on JavaScript, Angular and testing 5 | --- 6 | 7 | # References 8 | 9 | - *[Angular: Grundlagen, fortgeschrittene Themen und Best Practices](https://angular-buch.com/)*, Second Edition, Ferdinand Malcher, Johannes Hoppe, Danny Koppenhagen. dpunkt.verlag, 2019. ISBN 978-3-86490-646-6 10 | - *[Testing Angular Applications](https://www.manning.com/books/testing-angular-applications)*, Jesse Palmer, Corinna Cohn, Mike Giambalvo, Craig Nishina. Manning Publications, 2018. ISBN 978-1-61729-364-1 11 | - *[Testing JavaScript Applications](https://www.manning.com/books/testing-javascript-applications)*, Lucas da Costa. Manning Publications, 2021. ISBN 978-1-61729-791-5 12 | - *[JavaScript Testing Recipes](https://shop.jcoglan.com/javascript-testing-recipes/)*, James Coglan, 2016. 13 | 14 | 15 | -------------------------------------------------------------------------------- /robots.txt: -------------------------------------------------------------------------------- 1 | User-agent: AdsBot-Google 2 | User-agent: AI2Bot 3 | User-agent: Ai2Bot-Dolma 4 | User-agent: Amazonbot 5 | User-agent: anthropic-ai 6 | User-agent: Applebot 7 | User-agent: Applebot-Extended 8 | User-agent: AwarioRssBot 9 | User-agent: AwarioSmartBot 10 | User-agent: Bytespider 11 | User-agent: CCBot 12 | User-agent: ChatGPT-User 13 | User-agent: Claude-Web 14 | User-agent: ClaudeBot 15 | User-agent: cohere-ai 16 | User-agent: DataForSeoBot 17 | User-agent: Diffbot 18 | User-agent: FacebookBot 19 | User-agent: facebookexternalhit 20 | User-agent: FriendlyCrawler 21 | User-agent: Google-Extended 22 | User-agent: GoogleOther 23 | User-agent: GoogleOther-Image 24 | User-agent: GoogleOther-Video 25 | User-agent: GPTBot 26 | User-agent: iaskspider/2.0 27 | User-agent: ICC-Crawler 28 | User-agent: ImagesiftBot 29 | User-agent: img2dataset 30 | User-agent: magpie-crawler 31 | User-agent: Meta-ExternalAgent 32 | User-agent: Meta-ExternalFetcher 33 | User-agent: OAI-SearchBot 34 | User-agent: omgili 35 | User-agent: omgilibot 36 | User-agent: peer39_crawler 37 | User-agent: peer39_crawler/1.0 38 | User-agent: PerplexityBot 39 | User-agent: PetalBot 40 | User-agent: Scrapy 41 | User-agent: Timpibot 42 | User-agent: VelenPublicWebCrawler 43 | User-agent: Webzio-Extended 44 | User-agent: YouBot 45 | Disallow: / 46 | -------------------------------------------------------------------------------- /service-worker.js: -------------------------------------------------------------------------------- 1 | const VERSION = 'v6'; 2 | const PAGES_CACHE = `${VERSION}_PAGES`; 3 | const OFFLINE_PAGE = 'offline.html'; 4 | const CACHED_RESOURCES = [ 5 | OFFLINE_PAGE, 6 | '/', 7 | '/introduction/', 8 | '/target-audience/', 9 | '/terminology/', 10 | '/testing-principles/', 11 | '/example-applications/', 12 | '/angular-testing-principles/', 13 | '/test-suites-with-jasmine/', 14 | '/faking-dependencies/', 15 | '/debugging-tests/', 16 | '/testing-components/', 17 | '/testing-components-with-children/', 18 | '/testing-components-depending-on-services/', 19 | '/testing-complex-forms/', 20 | '/testing-components-with-spectator/', 21 | '/testing-services/', 22 | '/testing-pipes/', 23 | '/testing-directives/', 24 | '/testing-modules/', 25 | '/measuring-code-coverage/', 26 | '/end-to-end-testing/', 27 | '/summary/', 28 | '/index-of-example-applications/', 29 | '/references/', 30 | '/acknowledgements/', 31 | '/about/', 32 | '/license/', 33 | '/assets/css/book.css', 34 | '/assets/img/flying-probe-672-cavif-q60.avif', 35 | '/assets/img/flying-probe-1344-cavif-q50.avif', 36 | '/assets/img/flying-probe-672-cwebp-q80.webp', 37 | '/assets/img/flying-probe-1344-cwebp-q80.webp', 38 | '/assets/img/flying-probe-672-q85.jpg', 39 | '/assets/img/flying-probe-1344-q65.jpg', 40 | '/assets/img/favicon.svg', 41 | '/assets/img/favicon-194x194.png', 42 | '/assets/fonts/noto-sans-normal-normal-latin.woff2', 43 | '/assets/fonts/noto-sans-italic-normal-latin.woff2', 44 | '/assets/fonts/noto-sans-normal-bold-latin.woff2', 45 | '/assets/js/highlight-toc.js', 46 | '/assets/js/iframe-buttons.js', 47 | '/assets/js/collapse-toc.js', 48 | ]; 49 | 50 | addEventListener('install', (event) => { 51 | skipWaiting(); 52 | 53 | event.waitUntil( 54 | fetch(OFFLINE_PAGE).then((response) => 55 | caches.open(PAGES_CACHE).then((cache) => 56 | cache.put(OFFLINE_PAGE, response) 57 | ) 58 | ) 59 | ); 60 | }); 61 | 62 | addEventListener('activate', (event) => { 63 | event.waitUntil( 64 | caches.keys().then((keys) => 65 | Promise.all( 66 | keys 67 | .filter((key) => !key.startsWith(VERSION)) 68 | .map((key) => { 69 | console.log('Delete from cache', key); 70 | return caches.delete(key); 71 | }) 72 | ) 73 | ) 74 | ); 75 | }); 76 | 77 | function isRelevantRequest(method, url) { 78 | const urlParts = new URL(url); 79 | return ( 80 | method === 'GET' && 81 | urlParts.origin === location.origin && 82 | CACHED_RESOURCES.some((resourceUrl) => resourceUrl === urlParts.pathname) 83 | ); 84 | } 85 | 86 | addEventListener('fetch', (event) => { 87 | const { request } = event; 88 | const { method, url } = request; 89 | if (!isRelevantRequest(method, url)) { 90 | return; 91 | } 92 | event.respondWith( 93 | fetch(request) 94 | .then((response) => { 95 | const responseClone = response.clone(); 96 | caches.open(PAGES_CACHE).then((cache) => { 97 | cache.put(request, responseClone); 98 | }); 99 | return response; 100 | }) 101 | .catch(() => 102 | caches.match(request).then((responseFromCache) => { 103 | if (responseFromCache) { 104 | return responseFromCache; 105 | } 106 | // Serve offline page 107 | return caches 108 | .open(PAGES_CACHE) 109 | .then((cache) => cache.match(OFFLINE_PAGE)); 110 | }) 111 | ) 112 | ); 113 | }); 114 | -------------------------------------------------------------------------------- /summary.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Summary 4 | description: Recommendations on how to approach testing Angular applications 5 | --- 6 | 7 | # Summary 8 | 9 | 16 | 17 | Writing tests is often a frustrating experience that comes on top of implementation troubles. The logical and technical complexity is overwhelming and intimidating. All this drains motivation. 18 | 19 | The goal of this guide is to dispel the fear of testing. While testing Angular applications is a complex matter, this guide breaks it down into small, approachable steps and aims to give a well-balanced overview. 20 | 21 | Find a testing strategy that reduces the frustration and benefits the quality of your software. Once you have written tests for a couple of features, you will learn which tests are worthwhile – tests that uncover bugs and prevent regressions. Continue with these successes, then slowly explore other kind of tests. 22 | 23 | Luckily, the Angular community works steadily to make testing accessible. Angular’s architecture facilitates the testing of all relevant parts. The framework ships with robust testing tools. If they do not fit your needs, there are mature community projects with alternative workflows. 24 | 25 | Testing does not only make your software more reliable, but also evolves your coding practice in the long run. It requires to write testable code, and testable code is usually simpler. 26 | 27 | Automated software testing is challenging and rewarding for various reasons. Despite all troubles, that makes it fascinating. 28 | 29 | 30 | -------------------------------------------------------------------------------- /target-audience.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Target Audience 4 | description: What you should know when reading this book 5 | --- 6 | 7 | # Target audience 8 | 9 | 16 | 17 | The target audience of this guide are intermediate Angular developers. You should be familiar with Angular’s core concepts. 18 | 19 | 20 | 21 | This guide teaches you how to test Angular application parts like Components and Services. It assumes you know how to implement them, but not how to test them properly. If you have questions regarding Angular’s core concepts, please refer to the [official Angular documentation](https://angular.io/docs). 22 | 23 | If you have not used individual concepts yet, like Directives, that is fine. You can simply skip the related chapters and pick chapters you are interested in. 24 | 25 | 26 | 27 | Furthermore, this guide is not an introduction to JavaScript or TypeScript. It assumes you have enough JavaScript and TypeScript knowledge to write the implementation and test code you need. Of course, this guide will explain special idioms commonly used for testing. 28 | 29 | The official Angular documentation offers a comprehensive [guide on testing](https://angular.io/guide/testing). It is a recommended reading, but this guide does not assume you have read it. 30 | 31 | 32 | -------------------------------------------------------------------------------- /terminology.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Terminology 4 | description: How this book uses Angular technical terms 5 | --- 6 | 7 | # Terminology 8 | 9 | 15 | 16 | Before we dive in, a quick note regarding the technical terms. 17 | 18 | Some words have a special meaning in the context of Angular. In the broader JavaScript context, they have plenty other meanings. This guide tries to distinguish these meanings by using a different letter case. 19 | 20 | When referring to core Angular concepts, this guide uses **upper case**: 21 | 22 | *Module, Component, Service, Input, Output, Directive, Pipe*, etc. 23 | 24 | When using these terms in the general sense, this guide uses **lower case**: 25 | 26 | *module, component, service, input, output*, etc. 27 | 28 | 29 | -------------------------------------------------------------------------------- /test-suites-with-jasmine.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Test suites with Jasmine 4 | description: How to create and structure efficient tests using the Jasmine library 5 | --- 6 | 7 | # Test suites with Jasmine 8 | 9 | 17 | 18 | Angular ships with Jasmine, a JavaScript framework that enables you to write and execute unit and integration tests. Jasmine consists of three important parts: 19 | 20 | 1. A library with classes and functions for constructing tests. 21 | 2. A test execution engine. 22 | 3. A reporting engine that outputs test results in different formats. 23 | 24 | If you are new to Jasmine, it is recommended to read the [official Jasmine tutorial](https://jasmine.github.io/tutorials/your_first_suite). This guide provides a short introduction to Jasmine, exploring the basic structure and terminology that will be used throughout this guide. 25 | 26 | ## Creating a test suite 27 | 28 | In terms of Jasmine, a test consists of one or more **suites**. A suite is declared with a `describe` block: 29 | 30 | ```typescript 31 | describe('Suite description', () => { 32 | /* … */ 33 | }); 34 | ``` 35 | 36 | Each suite *describes* a piece of code, the *code under test*. 37 | 38 | 41 | 42 | `describe` is a function that takes two parameters. 43 | 44 | 1. A string with a human-readable name. Typically the name of the function or class under test. For example, `describe('CounterComponent', /* … */)` is the suite that tests the `CounterComponent` class. 45 | 2. A function containing the suite definition. 46 | 47 | A `describe` block groups related specs that we will learn about in the next chapter. 48 | 49 | 52 | 53 | `describe` blocks can be nested to structure big suites and divide them into logical sections: 54 | 55 | ```typescript 56 | describe('Suite description', () => { 57 | describe('One aspect', () => { 58 | /* … */ 59 | }); 60 | describe('Another aspect', () => { 61 | /* … */ 62 | }); 63 | }); 64 | ``` 65 | 66 | Nested `describe` blocks add a human-readable description to a group of specs. They can also host their own setup and teardown logic. 67 | 68 | ## Specifications 69 | 70 | 73 | 74 | Each suit consists of one or more *specifications*, or short, **specs**. A spec is declared with an `it` block: 75 | 76 | ```typescript 77 | describe('Suite description', () => { 78 | it('Spec description', () => { 79 | /* … */ 80 | }); 81 | /* … more specs … */ 82 | }); 83 | ``` 84 | 85 | Again, `it` is a function that takes two parameters. The first parameter is a string with a human-readable description. The second parameter is a function containing the spec code. 86 | 87 | 88 | 89 | The pronoun `it` refers to the code under test. `it` should be the subject of a human-readable sentence that asserts the behavior of the code under test. The spec code then proves this assertion. This style of writing specs originates from the concept of Behavior-Driven Development (BDD). 90 | 91 | One goal of BDD is to describe software behavior in a natural language – in this case, English. Every stakeholder should be able to read the `it` sentences and understand how the code is supposed to behave. Team members without JavaScript knowledge should be able to add more requirements by forming `it does something` sentences. 92 | 93 | Ask yourself, what does the code under test do? For example, in case of a `CounterComponent`, *it* increments the counter value. And *it* resets the counter to a specific value. So you could write: 94 | 95 | ```typescript 96 | it('increments the count', () => { 97 | /* … */ 98 | }); 99 | it('resets the count', () => { 100 | /* … */ 101 | }); 102 | ``` 103 | 104 | After `it`, typically a verb follows, like `increments` and `resets` in the example. 105 | 106 | 107 | 108 | Some people prefer to write `it('should increment the count', /* … */)`, but `should` bears no additional meaning. The nature of a spec is to state what the code under test *should* do. The word “should” is redundant and just makes the sentence longer. This guide recommends to simply state what the code does. 109 | 110 |
111 | - [Jasmine tutorial: Your first suite](https://jasmine.github.io/tutorials/your_first_suite) 112 |
113 | 114 | ## Structure of a test 115 | 116 | Inside the `it` block lies the actual testing code. Irrespective of the testing framework, the testing code typically consists of three phases: **Arrange, Act and Assert**. 117 | 118 | 119 | 120 | 1. **Arrange** is the preparation and setup phase. For example, the class under test is instantiated. Dependencies are set up. Spies and fakes are created. 121 | 2. **Act** is the phase where interaction with the code under test happens. For example, a method is called or an HTML element in the DOM is clicked. 122 | 3. **Assert** is the phase where the code behavior is checked and verified. For example, the actual output is compared to the expected output. 123 | 124 | How could the structure of the spec `it('resets the count', /* … */)` for the `CounterComponent` look like? 125 | 126 | 1.

Arrange:

127 | 128 | - Create an instance of `CounterComponent`. 129 | - Render the Component into the document. 130 | 131 | 2.

Act:

132 | 133 | - Find and focus the reset input field. 134 | - Enter the text “5”. 135 | - Find and click the “Reset” button. 136 | 137 | 3.

Assert:

138 | 139 | - Expect that the displayed count now reads “5”. 140 | 141 | 142 | 143 | This structure makes it easier to come up with a test and also to implement it. Ask yourself: 144 | 145 | - What is the necessary setup? Which dependencies do I need to provide? How do they behave? (*Arrange*) 146 | - What is the user input or API call that triggers the behavior I would like to test? (*Act*) 147 | - What is the expected behavior? How do I prove that the behavior is correct? (*Assert*) 148 | 149 | 150 | 151 | In Behavior-Driven Development (BDD), the three phases of a test are fundamentally the same. But they are called **Given, When and Then**. These plain English words try to avoid technical jargon and pose a natural way to think of a test’s structure: “*Given* these conditions, *when* the user interacts with the application, *then* it behaves in a certain way.” 152 | 153 | ## Expectations 154 | 155 | In the *Assert* phase, the test compares the actual output or return value to the expected output or return value. If they are the same, the test passes. If they differ, the test fails. 156 | 157 | Let us examine a simple contrived example, an `add` function: 158 | 159 | ```typescript 160 | const add = (a, b) => a + b; 161 | ``` 162 | 163 | A primitive test without any testing tools could look like this: 164 | 165 | ```typescript 166 | const expectedValue = 5; 167 | const actualValue = add(2, 3); 168 | if (expectedValue !== actualValue) { 169 | throw new Error( 170 | `Wrong return value: ${actualValue}. Expected: ${expectedValue}` 171 | ); 172 | } 173 | ``` 174 | 175 | 178 | 179 | We could write that code in a Jasmine spec, but Jasmine allows us to create expectations in an easier and more concise manner: The `expect` function together with a **matcher**. 180 | 181 | ```typescript 182 | const expectedValue = 5; 183 | const actualValue = add(2, 3); 184 | expect(actualValue).toBe(expectedValue); 185 | ``` 186 | 187 | First, we pass the actual value to the `expect` function. It returns an expectation object with methods for checking the actual value. We would like to compare the actual value to the expected value, so we use the `toBe` matcher. 188 | 189 | 190 | 191 | `toBe` is the simplest matcher that applies to all possible JavaScript values. Internally, it uses JavaScript’s strict equality operator `===`. expect(actualValue)​.toBe(expectedValue) essentially runs `actualValue === expectedValue`. 192 | 193 | `toBe` is useful to compare primitive values like strings, numbers and booleans. For objects, `toBe` matches only if the actual and the expected value are the very same object. `toBe` fails if two objects are not identical, even if they happen to have the same properties and values. 194 | 195 | For checking the deep equality of two objects, Jasmine offers the `toEqual` matcher. This example illustrates the difference: 196 | 197 | ```typescript 198 | // Fails, the two objects are not identical 199 | expect({ name: 'Linda' }).toBe({ name: 'Linda' }); 200 | 201 | // Passes, the two objects are not identical but deeply equal 202 | expect({ name: 'Linda' }).toEqual({ name: 'Linda' }); 203 | ``` 204 | 205 | Jasmine has numerous useful matchers built-in, `toBe` and `toEqual` being the most common. You can add custom matchers to hide a complex check behind a short name. 206 | 207 | 208 | 209 | The pattern `expect(actualValue).toEqual(expectedValue)` originates from Behavior-Driven Development (BDD) again. The `expect` function call and the matcher methods form a human-readable sentence: “Expect the actual value to equal the expected value.” The goal is to write a specification that is as readable as a plain text but can be verified automatically. 210 | 211 |
212 | - [Jasmine documentation: Built-in matchers](https://jasmine.github.io/api/edge/matchers) 213 | - [Jasmine tutorials: Custom matchers](https://jasmine.github.io/tutorials/custom_matcher) 214 |
215 | 216 | ## Efficient test suites 217 | 218 | When writing multiple specs in one suite, you quickly realize that the *Arrange* phase is similar or even identical across these specs. For example, when testing the `CounterComponent`, the *Arrange* phase always consists of creating a Component instance and rendering it into the document. 219 | 220 | 221 | 222 | This setup is repeated over and over, so it should be defined once in a central place. You could write a `setup` function and call it at the beginning of each spec. But using Jasmine, you can declare code that is called before and after each spec, or before and after all specs. 223 | 224 | For this purpose, Jasmine provides four functions: `beforeEach`, `afterEach`, `beforeAll` and `afterAll`. They are called inside of a `describe` block, just like `it`. They expect one parameter, a function that is called at the given stages. 225 | 226 | ```typescript 227 | describe('Suite description', () => { 228 | beforeAll(() => { 229 | console.log('Called before all specs are run'); 230 | }); 231 | afterAll(() => { 232 | console.log('Called after all specs are run'); 233 | }); 234 | 235 | beforeEach(() => { 236 | console.log('Called before each spec is run'); 237 | }); 238 | afterEach(() => { 239 | console.log('Called after each spec is run'); 240 | }); 241 | 242 | it('Spec 1', () => { 243 | console.log('Spec 1'); 244 | }); 245 | it('Spec 2', () => { 246 | console.log('Spec 2'); 247 | }); 248 | }); 249 | ``` 250 | 251 | This suite has two specs and defines shared setup and teardown code. The output is: 252 | 253 | ``` 254 | Called before all specs are run 255 | Called before each spec is run 256 | Spec 1 257 | Called after each spec is run 258 | Called before each spec is run 259 | Spec 2 260 | Called after each spec is run 261 | Called after all specs are run 262 | ``` 263 | 264 | Most tests we are going to write will have a `beforeEach` block to host the *Arrange* code. 265 | 266 | 267 | -------------------------------------------------------------------------------- /testing-modules.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Testing Modules 4 | description: Automated smoke tests for Angular Modules 5 | --- 6 | 7 | # Testing Modules 8 | 9 | 15 | 16 | Modules are central parts of Angular applications. Often they contain important setup code. Yet they are hard to test since there is no typical logic, only sophisticated configuration. 17 | 18 | 19 | 20 | Angular Modules are classes, but most of the time, the class itself is empty. The essence lies in the metadata set with `@NgModule({ … })`. 21 | 22 | We could sneak into the metadata and check whether certain Services are provided, whether third-party Modules are imported and whether Components are exported. 23 | 24 | But such a test would simply **mirror the implementation**. Code duplication does not give you more confidence, it only increases the cost of change. 25 | 26 | Should we write tests for Modules at all? If there is a reference error in the Module, the compilation step (`ng build`) fails before the automated tests scrutinize the build. “Failing fast” is good from a software quality perspective. 27 | 28 | 29 | 30 | There are certain Module errors that only surface during runtime. These can be caught with a *smoke test*. Given this Module: 31 | 32 | ```typescript 33 | import { NgModule } from '@angular/core'; 34 | import { CommonModule } from '@angular/common'; 35 | import { ExampleComponent } from './example.component'; 36 | 37 | @NgModule({ 38 | declarations: [ExampleComponent], 39 | imports: [CommonModule], 40 | }) 41 | export class FeatureModule {} 42 | ``` 43 | 44 | We write this smoke test: 45 | 46 | ```typescript 47 | import { TestBed } from '@angular/core/testing'; 48 | import { FeatureModule } from './example.module'; 49 | 50 | describe('FeatureModule', () => { 51 | beforeEach(() => { 52 | TestBed.configureTestingModule({ 53 | imports: [FeatureModule], 54 | }); 55 | }); 56 | 57 | it('initializes', () => { 58 | const module = TestBed.inject(FeatureModule); 59 | expect(module).toBeTruthy(); 60 | }); 61 | }); 62 | ``` 63 | 64 | The integration test uses the `TestBed` to import the Module under test. It verifies that no error occurs when importing the Module. 65 | 66 | 67 | -------------------------------------------------------------------------------- /testing-pipes.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: chapter 3 | title: Testing Pipes 4 | description: How to test simple and complex, pure and impure Angular Pipes 5 | --- 6 | 7 | # Testing Pipes 8 | 9 | 15 | 16 | An Angular Pipe is a special function that is called from a Component template. Its purpose is to transform a value: You pass a value to the Pipe, the Pipe computes a new value and returns it. 17 | 18 | The name Pipe originates from the vertical bar “\|” that sits between the value and the Pipe’s name. The concept as well as the “\|” syntax originate from Unix pipes and Unix shells. 19 | 20 | In this example, the value from `user.birthday` is transformed by the `date` Pipe: 21 | 22 | ``` 23 | {% raw %}{{ user.birthday | date }}{% endraw %} 24 | ``` 25 | 26 | 27 | 28 | Pipes are often used for internationalization, including translation of labels and messages, formatting of dates, times and various numbers. In these cases, the Pipe input value should not be shown to the user. The output value is user-readable. 29 | 30 | Examples for built-in Pipes are `DatePipe`, `CurrencyPipe` and `DecimalPipe`. They format dates, amounts of money and numbers, respectively, according to the localization settings. Another well-known Pipe is the `AsyncPipe` which unwraps an Observable or Promise. 31 | 32 | 33 | 34 | Most Pipes are *pure*, meaning they merely take a value and compute a new value. They do not have *side effects*: They do not change the input value and they do not change the state of other application parts. Like pure functions, pure Pipes are relatively easy to test. 35 | 36 | ## GreetPipe 37 | 38 | Let us study the structure of a Pipe first to find ways to test it. In essence, a Pipe is class with a public `transform` method. Here is a simple Pipe that expects a name and greets the user. 39 | 40 | ```typescript 41 | import { Pipe, PipeTransform } from '@angular/core'; 42 | 43 | @Pipe({ name: 'greet' }) 44 | export class GreetPipe implements PipeTransform { 45 | transform(name: string): string { 46 | return `Hello, ${name}!`; 47 | } 48 | } 49 | ``` 50 | 51 | In a Component template, we transform a value using the Pipe: 52 | 53 | ``` 54 | {% raw %}{{ 'Julie' | greet }}{% endraw %} 55 | ``` 56 | 57 | The `GreetPipe` take the string `'Julie'` and computes a new string, `'Hello, Julie!'`. 58 | 59 | 60 | 61 | There are two important ways to test a Pipe: 62 | 63 | 1. Create an instance of the Pipe class manually. Then call the `transform` method. 64 | 65 | This way is fast and straight-forward. It requires minimal setup. 66 | 67 | 2. Set up a `TestBed`. Render a host Component that uses the Pipe. Then check the text content in the DOM. 68 | 69 | This way closely mimics how the Pipe is used in practice. It also tests the name of the Pipe, as declared in the `@Pipe()` decorator. 70 | 71 | Both ways allow to test Pipes that depend on Services. Either we provide the original dependencies, writing an integration test. Or we provide fake dependencies, writing a unit test. 72 | 73 | ## GreetPipe test 74 | 75 | The `GreetPipe` does not have any dependencies. We opt for the first way and write a unit test that examines the single instance. 76 | 77 | First, we create a Jasmine test suite. In a `beforeEach` block, we create an instance of `GreetPipe`. In the specs, we scrutinize the `transform` method. 78 | 79 | ```typescript 80 | describe('GreetPipe', () => { 81 | let greetPipe: GreetPipe; 82 | 83 | beforeEach(() => { 84 | greetPipe = new GreetPipe(); 85 | }); 86 | 87 | it('says Hello', () => { 88 | expect(greetPipe.transform('Julie')).toBe('Hello, Julie!'); 89 | }); 90 | }); 91 | ``` 92 | 93 | We call the `transform` method with the string `'Julie'` and expect the output `'Hello, Julie!'`. 94 | 95 | This is everything that needs to be tested in the `GreetPipe` example. If the `transform` method contains more logic that needs to be tested, we add more specs that call the method with different input. 96 | 97 | ## Testing Pipes with dependencies 98 | 99 | Many Pipes depend on local settings, including the user interface language, date and number formatting rules, as well as the selected country, region or currency. 100 | 101 | We are introducing and testing the `TranslatePipe`, a complex Pipe with a Service dependency. 102 | 103 |
104 | - [TranslatePipe: Source code](https://github.com/molily/translate-pipe) 105 | - [TranslatePipe: Run the app](https://molily.github.io/translate-pipe/) 106 |
107 | 108 | 111 | 112 | 117 | 118 | The example application lets you change the user interface language during runtime. A popular solution for this task is the [ngx-translate](https://github.com/ngx-translate/core) library. For the purpose of this guide, we will adopt ngx-translate’s proven approach but implement and test the code ourselves. 119 | 120 | ### TranslateService 121 | 122 | The current language is stored in the `TranslateService`. This Service also loads and holds the translations for the current language. 123 | 124 | The translations are stored in a map of keys and translation strings. For example, the key `greeting` translates to “Hello!” if the current language is English. 125 | 126 | The `TranslateService` looks like this: 127 | 128 | ```typescript 129 | import { HttpClient } from '@angular/common/http'; 130 | import { EventEmitter, Injectable } from '@angular/core'; 131 | import { Observable, of } from 'rxjs'; 132 | import { map, take } from 'rxjs/operators'; 133 | 134 | export interface Translations { 135 | [key: string]: string; 136 | } 137 | 138 | @Injectable() 139 | export class TranslateService { 140 | /** The current language */ 141 | private currentLang = 'en'; 142 | 143 | /** Translations for the current language */ 144 | private translations: Translations | null = null; 145 | 146 | /** Emits when the language change */ 147 | public onTranslationChange = new EventEmitter(); 148 | 149 | constructor(private http: HttpClient) { 150 | this.loadTranslations(this.currentLang); 151 | } 152 | 153 | /** Changes the language */ 154 | public use(language: string): void { 155 | this.currentLang = language; 156 | this.loadTranslations(language); 157 | } 158 | 159 | /** Translates a key asynchronously */ 160 | public get(key: string): Observable { 161 | if (this.translations) { 162 | return of(this.translations[key]); 163 | } 164 | return this.onTranslationChange.pipe( 165 | take(1), 166 | map((translations) => translations[key]) 167 | ); 168 | } 169 | 170 | /** Loads the translations for the given language */ 171 | private loadTranslations(language: string): void { 172 | this.translations = null; 173 | this.http 174 | .get(`assets/${language}.json`) 175 | .subscribe((translations) => { 176 | this.translations = translations; 177 | this.onTranslationChange.emit(translations); 178 | }); 179 | } 180 | } 181 | ``` 182 | 183 | This is what the Service provides: 184 | 185 | 1. `use` method: Set the current language and load the translations as JSON via HTTP. 186 | 2. `get` method: Get the translation for a key. 187 | 3. `onTranslationChange` `EventEmitter`: Observing changes on the translations as a result of `use`. 188 | 189 | In the example project, the `AppComponent` depends on the `TranslateService`. On creation, the Service loads the English translations. The `AppComponent` renders a select field allowing the user to change the language. 190 | 191 |
192 | - [TranslateService: implementation code](https://github.com/molily/translate-pipe/blob/main/src/app/translate.service.ts) 193 | - [TranslateService: test code](https://github.com/molily/translate-pipe/blob/main/src/app/translate.service.spec.ts) 194 |
195 | 196 | ### TranslatePipe 197 | 198 | To show a translated label, a Component could call the Service’s `get` method manually for each translation key. Instead, we introduce the `TranslatePipe` to do the heavy lifting. It lets us write: 199 | 200 | ``` 201 | {% raw %}{{ 'greeting' | translate }}{% endraw %} 202 | ``` 203 | 204 | This translates the key `'greeting'`. 205 | 206 | Here is the code: 207 | 208 | ```typescript 209 | import { 210 | ChangeDetectorRef, 211 | OnDestroy, 212 | Pipe, 213 | PipeTransform, 214 | } from '@angular/core'; 215 | import { Subscription } from 'rxjs'; 216 | 217 | import { TranslateService } from './translate.service'; 218 | 219 | @Pipe({ 220 | name: 'translate', 221 | pure: false, 222 | }) 223 | export class TranslatePipe implements PipeTransform, OnDestroy { 224 | private lastKey: string | null = null; 225 | private translation: string | null = null; 226 | 227 | private onTranslationChangeSubscription: Subscription; 228 | private getSubscription: Subscription | null = null; 229 | 230 | constructor( 231 | private changeDetectorRef: ChangeDetectorRef, 232 | private translateService: TranslateService 233 | ) { 234 | this.onTranslationChangeSubscription = 235 | this.translateService.onTranslationChange.subscribe( 236 | () => { 237 | if (this.lastKey) { 238 | this.getTranslation(this.lastKey); 239 | } 240 | } 241 | ); 242 | } 243 | 244 | public transform(key: string): string | null { 245 | if (key !== this.lastKey) { 246 | this.lastKey = key; 247 | this.getTranslation(key); 248 | } 249 | return this.translation; 250 | } 251 | 252 | private getTranslation(key: string): void { 253 | this.getSubscription?.unsubscribe(); 254 | this.getSubscription = this.translateService 255 | .get(key) 256 | .subscribe((translation) => { 257 | this.translation = translation; 258 | this.changeDetectorRef.markForCheck(); 259 | this.getSubscription = null; 260 | }); 261 | } 262 | 263 | public ngOnDestroy(): void { 264 | this.onTranslationChangeSubscription.unsubscribe(); 265 | this.getSubscription?.unsubscribe(); 266 | } 267 | } 268 | ``` 269 | 270 | 271 | 272 | The `TranslatePipe` is *impure* because the translations are loaded asynchronously. When called the first time, the `transform` method cannot return the correct translation synchronously. It calls the `TranslateService`’s `get` method which returns an Observable. 273 | 274 | 275 | 276 | Once the translation is loaded, the `TranslatePipe` saves it and notifies the Angular change detector. In particular, it marks the corresponding view as changed by calling [`ChangeDetectorRef`’s `markForCheck`](https://angular.io/api/core/ChangeDetectorRef#markForCheck) method. 277 | 278 | In turn, Angular re-evaluates every expression that uses the Pipe, like `'greeting' | translate`, and calls the `transform` method again. Finally, `transform` returns the right translation synchronously. 279 | 280 | 281 | 282 | The same process happens when the user changes the language and new translations are loaded. The Pipe subscribes to `TranslateService`’s `onTranslationChange` and calls the `TranslateService` again to get the new translation. 283 | 284 |
285 | - [TranslatePipe: implementation code](https://github.com/molily/translate-pipe/blob/main/src/app/translate.pipe.ts) 286 | - [Angular API reference: ChangeDetectorRef](https://angular.io/api/core/ChangeDetectorRef) 287 |
288 | 289 | ### TranslatePipe test 290 | 291 | Now let us test the `TranslatePipe`! We can either write a test that integrates the `TranslateService` dependency. Or we write a unit test that replaces the dependency with a fake. 292 | 293 | `TranslateService` performs HTTP requests to load the translations. We should avoid these side effects when testing `TranslatePipe`. So let us fake the Service to write a unit test. 294 | 295 | ```typescript 296 | let translateService: Pick< 297 | TranslateService, 'onTranslationChange' | 'get' 298 | >; 299 | /* … */ 300 | translateService = { 301 | onTranslationChange: new EventEmitter(), 302 | get(key: string): Observable { 303 | return of(`Translation for ${key}`); 304 | }, 305 | }; 306 | ``` 307 | 308 | The fake is a partial implementation of the original. The `TranslatePipe` under test only needs the `onTranslationChange` property and the `get` method. The latter returns a fake translation including the key so we can test that the key was passed correctly. 309 | 310 | 311 | 312 | Now we need to decide whether to test the Pipe directly or within a host Component. Neither solution is significantly easier or more robust. You will find both solutions in the example project. In this guide, we will discuss the solution with `TestBed` and host Component. 313 | 314 | Let us start with the host Component: 315 | 316 | ```typescript 317 | const key1 = 'key1'; 318 | const key2 = 'key2'; 319 | 320 | @Component({ 321 | template: '{% raw %}{{ key | translate }}{% endraw %}', 322 | }) 323 | class HostComponent { 324 | public key = key1; 325 | } 326 | ``` 327 | 328 | This Component uses the `TranslatePipe` to translate its `key` property. Per default, it is set to `key1`. There is also a second constant `key2` for testing the key change later. 329 | 330 | Let us set up the test suite: 331 | 332 | ```typescript 333 | describe('TranslatePipe: with TestBed and HostComponent', () => { 334 | let fixture: ComponentFixture; 335 | let translateService: Pick< 336 | TranslateService, 'onTranslationChange' | 'get' 337 | >; 338 | 339 | beforeEach(async () => { 340 | translateService = { 341 | onTranslationChange: new EventEmitter(), 342 | get(key: string): Observable { 343 | return of(`Translation for ${key}`); 344 | }, 345 | }; 346 | 347 | await TestBed.configureTestingModule({ 348 | declarations: [TranslatePipe, HostComponent], 349 | providers: [ 350 | { provide: TranslateService, useValue: translateService } 351 | ], 352 | }).compileComponents(); 353 | 354 | translateService = TestBed.inject(TranslateService); 355 | fixture = TestBed.createComponent(HostComponent); 356 | }); 357 | 358 | /* … */ 359 | }); 360 | ``` 361 | 362 | In the testing Module, we declare the Pipe under test and the `HostComponent`. For the `TranslateService`, we provide a fake object instead. Just like in a Component test, we create the Component and examine the rendered DOM. 363 | 364 | 365 | 366 | What needs to be tested? We need to check that `{% raw %}{{ key | translate }}{% endraw %}` evaluates to `Translation for key1`. There are two cases that need to be tested though: 367 | 368 | 1. The translations are already loaded. The Pipe’s `transform` method returns the correct translation synchronously. The Observable returned by `TranslateService`’s `get` emits the translation and completes immediately. 369 | 2. The translations are pending. `transform` returns `null` (or an outdated translation). The Observable completes at any time later. Then, the change detection is triggered, `transform` is called the second time and returns the correct translation. 370 | 371 | In the test, we write specs for both scenarios: 372 | 373 | ```typescript 374 | it('translates the key, sync service response', /* … */); 375 | it('translates the key, async service response', /* … */); 376 | ``` 377 | 378 | Let us start with the first case. The spec is straight-forward. 379 | 380 | ```typescript 381 | it('translates the key, sync service response', () => { 382 | fixture.detectChanges(); 383 | expectContent(fixture, 'Translation for key1'); 384 | }); 385 | ``` 386 | 387 | Remember, the `TranslateService` fake returns an Observable created with `of`. 388 | 389 | ```typescript 390 | return of(`Translation for ${key}`); 391 | ``` 392 | 393 | This Observable emits one value and completes immediately. This mimics the case in which the Service has already loaded the translations. 394 | 395 | We merely need to call `detectChanges`. Angular calls the Pipe’s `transform` method, which calls `TranslateService`’s `get`. The Observable emits the translation right away and `transform` passes it through. 396 | 397 | Finally, we use the [`expectContent` Component helper](https://github.com/molily/translate-pipe/blob/main/src/app/spec-helpers/element.spec-helper.ts) to test the DOM output. 398 | 399 | 400 | 401 | Testing the second case is trickier because the Observable needs to emit asynchronously. There are numerous ways to achieve this. We will use the [RxJS `delay` operator](https://rxjs.dev/api/operators/delay) for simplicity. 402 | 403 | At the same time, we are writing an asynchronous spec. That is, Jasmine needs to wait for the Observable and the expectations before the spec is finished. 404 | 405 | 408 | 409 | Again, there are several ways how to accomplish this. We are going to use Angular’s `fakeAsync` and `tick` functions. We have introduced them when [testing a form with async validators](../testing-complex-forms/#successful-form-submission). 410 | 411 | A quick recap: `fakeAsync` freezes time and prevents asynchronous tasks from being executed. The `tick` function then simulates the passage of time, executing the scheduled tasks. 412 | 413 | `fakeAsync` wraps the function passed to `it`: 414 | 415 | ```typescript 416 | it('translates the key, async service response', fakeAsync(() => { 417 | /* … */ 418 | }); 419 | ``` 420 | 421 | Next, we need to change the `TranslateService`’s `get` method to make it asynchronous. 422 | 423 | ```typescript 424 | it('translates the key, async service response', fakeAsync(() => { 425 | translateService.get = (key) => 426 | of(`Async translation for ${key}`).pipe(delay(100)); 427 | /* … */ 428 | }); 429 | ``` 430 | 431 | 432 | 433 | We still use `of`, but we delay the output by 100 milliseconds. The exact number does not matter as long as there is *some* delay greater or equal 1. 434 | 435 | Now, we can call `detectChanges` for the first time. 436 | 437 | ```typescript 438 | it('translates the key, async service response', fakeAsync(() => { 439 | translateService.get = (key) => 440 | of(`Async translation for ${key}`).pipe(delay(100)); 441 | fixture.detectChanges(); 442 | /* … */ 443 | }); 444 | ``` 445 | 446 | The Pipe’s `transform` method is called for the first time and returns `null` since the Observable does not emit a value immediately. 447 | 448 | So we expect that the output is empty: 449 | 450 | ```typescript 451 | it('translates the key, async service response', fakeAsync(() => { 452 | translateService.get = (key) => 453 | of(`Async translation for ${key}`).pipe(delay(100)); 454 | fixture.detectChanges(); 455 | expectContent(fixture, ''); 456 | /* … */ 457 | }); 458 | ``` 459 | 460 | 461 | 462 | Here comes the interesting part. We want the Observable to emit a value now. We simulate the passage of 100 milliseconds with `tick(100)`. 463 | 464 | ```typescript 465 | it('translates the key, async service response', fakeAsync(() => { 466 | translateService.get = (key) => 467 | of(`Async translation for ${key}`).pipe(delay(100)); 468 | fixture.detectChanges(); 469 | expectContent(fixture, ''); 470 | 471 | tick(100); 472 | /* … */ 473 | }); 474 | ``` 475 | 476 | This causes the Observable to emit the translation and complete. The Pipe receives the translation and saves it. 477 | 478 | To see a change in the DOM, we start a second change detection. The Pipe’s `transform` method is called for the second time and returns the correct translation. 479 | 480 | ```typescript 481 | it('translates the key, async service response', fakeAsync(() => { 482 | translateService.get = (key) => 483 | of(`Async translation for ${key}`).pipe(delay(100)); 484 | fixture.detectChanges(); 485 | expectContent(fixture, ''); 486 | 487 | tick(100); 488 | fixture.detectChanges(); 489 | expectContent(fixture, 'Async translation for key1'); 490 | })); 491 | ``` 492 | 493 | Testing these details may seem pedantic at first. But the logic in `TranslatePipe` exists for a reason. 494 | 495 | There are two specs left to write: 496 | 497 | ```typescript 498 | it('translates a changed key', /* … */); 499 | it('updates on translation change', /* … */); 500 | ``` 501 | 502 | The `TranslatePipe` receives the translation asynchronously and stores both the key and the translation. When Angular calls `transform` with the *same key* again, the Pipe returns the translation synchronously. Since the Pipe is marked as *impure*, Angular does not cache the `transform` result. 503 | 504 | 505 | 506 | When `translate` is called with a *different key*, the Pipe needs to fetch the new translation. We simulate this case by changing the `HostComponent`’s `key` property from `key1` to `key2`. 507 | 508 | ```typescript 509 | it('translates a changed key', () => { 510 | fixture.detectChanges(); 511 | fixture.componentInstance.key = key2; 512 | fixture.detectChanges(); 513 | expectContent(fixture, 'Translation for key2'); 514 | }); 515 | ``` 516 | 517 | After a change detection, the DOM contains the updated translation for `key2`. 518 | 519 | 520 | 521 | Last but no least, the Pipe needs to fetch a new translation from the `TranslateService` when the user changes the language and new translations have been loaded. For this purpose, the Pipe subscribes to the Service’s `onTranslationChange` emitter. 522 | 523 | Our `TranslateService` fake supports `onTranslationChange` as well, hence we call the `emit` method to simulate a translation change. Before, we let the Service return a different translation in order to see a change in the DOM. 524 | 525 | ```typescript 526 | it('updates on translation change', () => { 527 | fixture.detectChanges(); 528 | translateService.get = (key) => 529 | of(`New translation for ${key}`); 530 | translateService.onTranslationChange.emit({}); 531 | fixture.detectChanges(); 532 | expectContent(fixture, 'New translation for key1'); 533 | }); 534 | ``` 535 | 536 | We made it! Writing these specs is challenging without doubt. 537 | 538 | `TranslateService` and `TranslatePipe` are non-trivial examples with a proven API. The original classes from ngx-translate are more powerful. If you look for a robust and flexible solution, you should use the ngx-translate library directly. 539 | 540 |
541 | - [TranslatePipe: test code](https://github.com/molily/translate-pipe/blob/main/src/app/translate.pipe.spec.ts) 542 | - [Angular API reference: fakeAsync](https://angular.io/api/core/testing/fakeAsync) 543 | - [Angular API reference: tick](https://angular.io/api/core/testing/tick) 544 | - [RxJS: delay operator](https://rxjs.dev/api/operators/delay) 545 | - [ngx-translate](https://github.com/ngx-translate/core) 546 |
547 | 548 | 549 | 550 | --------------------------------------------------------------------------------