Test all code excerpts

[kwalrath]

This bug replaces #407, which is the equivalent for the pre-dart.dev version of this site. We'll need to be able to test all samples as null safety is released.

---

New pages that need tests for code excerpts:

• Dart cheatsheet codelab
• Dart language cheatsheet
• Dart async/await codelab

Old pages that should have tests for code excerpts, including DartPad code (which in most cases is contained in a Gist):

• src/_tutorials/web/fetch-data.md
  • Gists are out of date. E.g., the "Get portmanteaux" example fails. We should put the code in this repo instead of in gists. See src/codelabs/async-await.md (in particular, the code in the else statements for useIframe) for an example of how to do this.
  • Consider dropping or editing the "Implementation note"; is it really relevant to the reader's experience and/or understanding?
• examples/fetch_data: write tests or check web app build for problems examples/fetch_data: write tests or check web app build for problems #2113
• src/_tutorials/web/low-level-html/connect-dart-html.md
  • Noticed in the course of creating a DartPad-related PR (Edit DartPad embeds, add troubleshooting instructions #1956).
• src/_tutorials/web/low-level-html/add-elements
  • Has "new" and other signs of old code.

Lower priority code in new pages:

• Some pages migrated from the old webdev site:
  • webdev tool page (pubspec entry).
  • build_runner page (pubspec entry).

Other:

• New excerpts in language tour, including the one fixed in Update language-tour.md, fixed typo. #2184.
• Link/include mini, mini_with_style? #1959 Link/include mini, mini_with_style?
• Zones article code refresh (to the extent possible)? (no.67, 0.25%). Related 'Articles' page issue: should Zones be in the list? #1812.

Tested to some extent:

• codelabs/async-await: copies of runnable code are in the repo; it's possible for the gists and repo to get out of sync, though.

Done:

• src/_tutorials/server/cmdline.md; code added via Add directions for getting the args package #2101; see https://github.com/dart-lang/site-www/pull/2101/files#r347495897.
• Homepage DartPad examples shown under "Try Dart in your browser" at the end of the page.
• Recover and update examples/fetch_data Recover and update examples/fetch_data #2108
  • Uses HTML comments rather than code-excerpt instructions
• Recover dart:html library tour code and reinstate tests Recover dart:html library tour code and reinstate tests #2106
• src/_tutorials/server/get-started.md, Hello World DartDap sources
• Analyze/test cmdline tutorial code excerpts #1902. Dev > CLI & Server > Write Command-line Apps - code excerpts have popups.
• Analyze/test analysis-options page code excerpts #1912. T&T > Static Analysis > guides/language/analysis-options - varies pubspec analyzer options; will require separate projects. Might be worth testing analyzer and linter rules like in Fixing common type problems page to ensure that expected errors are generated (or not generated).
• Get-started server tutorial: analyze/test code excerpts #1921. Tutorial (VM): Get Started (very small code excerpts)
• build_runner page, see Use code-excerpt instruction for pubspec.yaml code in build_runner page #1217

Intentionally not testing:

• Native Extensions article Update Native Extensions article #980 - is this article still relevant? Or should / will it be replaced by https://dart.dev/server/c-interop? (won't write tests because this has a very small audience)
• Diagnostic messages These are copied from dart-lang/sdk and are tested by @bwilkerson.

[chalin]

Kathy, I've moved into the opening comment the work items that used to appear in separate comments. That will make it a bit easier to track.

[jddeep]

@kwalrath So I noticed the src for the Dart cheatsheet codelab to be here https://github.com/dart-lang/site-www/edit/master/src/codelabs/dart-cheatsheet.md. So if were to add the code-excerpt for the code snippet:

int a; // The initial value of a is null.
a ??= 3;
print(a); // <-- Prints 3.

a ??= 5;
print(a); // <-- Still prints 3.

Is there the code file for this snippet already there to be linked or we need to create first? Also should it be just a gist or we should add as .dart file in this repo itself?

[kwalrath]

You've got the right source file for the cheatsheet codelab, although it'd probably be easiest to edit it locally rather than in GitHub.

I believe that all of those samples are untested, and grepping the repo for ??= 3 brings up nothing. Gists aren't testable, so ideally we'd add .dart files to the repo so that Travis will analyze the code, and perhaps actually test it.

Once that code is in your copy of the repo, then in a separate commit (for the same branch & PR) you could add code-excerpt above each excerpt. If you have the local build working, then you can run tool/refresh-code-excerpts.sh to update the code excerpts — and if there are changes/mistakes, you'll see them in the diffs.

Does that make sense?

[jddeep]

Yes, @kwalrath that makes sense.
Am on it.

[jddeep]

@kwalrath Adding all the code snippets as in the cheatsheet.md file, into a single dart file, say, dart_cheatsheet.dart isn't feasible cause, in the .md file there are various objects and classes with the same name as for demonstration.
So should I go ahead to make separate code files(as fewer files needed) at /misc/bin/ of the repo?
If yes, could I open an issue to add the code files for this dart cheatsheet. Once that issue is resolved and we add the needed code files, I can direct to this issue with a PR for the code-excerpts.
Please do let me know your thoughts :) Thanks.

[kwalrath]

I'm fine with splitting this up into two PRs, although what I'm about to say next might change your mind...

To deal with multiple objects/classes having the same name, one possibility is to put them in different files, as you said. Another one is to change the names used in the samples, so they aren't all the same. (We generally don't do this, since the names were the same for a reason.) A technique we often use is to have one file with different names for the objects/classes — and then to modify them to be the same name by using replace in the code-excerpt.

I don't remember exactly where I've done the latter, but if you do the following command in your copy of the repo, you can see lots of examples of using replace in the language tour:

$ fgrep -R code-excerpt src/_guides/language/language-tour.md | grep replace

Many of those uses are for the purpose of highlighting (by surrounding it with [!...!]). For example, replace="/async|await/[!$&!]/g" highlights async and await in an excerpt. But other uses are to change the actual displayed code.

For example, instead of having myObject, you could have myObject1, myObject2, etc. and then use replace to change them all to myObject.

[jddeep]

@kwalrath Thanks for letting me know about this technique :) Will implement when I work on the next files.
Actually, I have already made different files for the code snippets used in the cheatsheet and will make a PR with the code files now. So should I direct/refer to this issue (#1803) only in that PR body or I should make a separate issue for adding the code files?
Thanks.

[kwalrath]

I'd love to see that PR and how Travis likes it. Did you find any issues with the code while creating those files?

It'd probably be good to have a separate issue for adding the cheatsheet code samples. (Then I can add that issue above by the cheatsheet item.) Either you or I can create that issue.

[jddeep]

Nope i didn't find any such issues while creating the files.
@kwalrath Could you then open the issue for the same and let me know. Will make the PR and direct to the issue. Thanks :)

[jddeep]

@kwalrath nvm :) have opened the issue for us.

[parlough]

This issue is quite out of date as a lot of progress has been made. I'm going to close this in favor of more specific issues as we determine excerpts are needed.