chore: test Academy exercises (#2097)

This is a proof of concept how we could test exercises in the academy:

- Exercises target real world websites, so they can easily break without
us knowing
- We could test them e.g. weekly, so it's not too noisy
- The solution should be as simple as possible, and capable running both
JavaScript and Python
- While working on the PoC I actually discovered one exercise which is
broken 95% of time due to aggressive anti-scraping protections, so I
changed it
- The test can be executed with `bats -r --print-output-on-failure .`
- Bats is a simple testing framework based on Bash, which allows to run
arbitrary programs and evaluate their output -
https://github.com/bats-core/bats-core Not sure yet how to get it inside
the CI, but on macOS it's just `brew install bats`

Todo:

- [x] Implement Python exercise
- [x] Implement JS exercise
- [x] Implement GitHub Action
- [x] Discuss with the team whether we want this
- [x] Document the solution
- [x] Port the rest of the exercises
- [x] Change the YAML to do just crons

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds a monthly GitHub Action and Bats-based suite to run Academy
JS/Python exercise solutions, embeds solutions into lessons, and updates
docs/ignore files.
> 
> - **CI**:
> - Add monthly and manual workflow `.github/workflows/test-academy.yml`
to run Academy exercises via Node (npm) and Python (uv).
> - **Testing**:
> - Introduce Bats-based tests for Academy exercises:
`sources/academy/**/exercises/test.bats` (JS & Python) executing
solutions and asserting outputs.
>   - New npm script `test:academy` and dev dependency `bats`.
> - **Docs/Academy content**:
> - Embed executable exercise solutions using `CodeBlock` +
`!!raw-loader` across JS/Python lessons (`04–12`), replacing inline
snippets.
> - Update several exercises (e.g., switch example from AliExpress to
LEGO) and add multiple new solution files
(Cheerio/BeautifulSoup/Crawlee).
> - **Repo**:
> - Update `.gitignore` to exclude exercise artifacts (`storage`,
`node_modules`, `package*.json`, `dataset.json`).
> - Document testing process in `CONTRIBUTING.md` (broken links check +
Academy exercises CI).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
118a550. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: honzajavorek

.github/workflows/test-academy.yml

@@ -0,0 +1,31 @@
+name: Test Academy
+
+on:
+    schedule:
+        - cron: "0 3 1 * *"  # at 3am UTC on 1st day of month
+    workflow_dispatch:  # allows running this workflow manually from the Actions tab
+
+jobs:
+    test-exercises:
+        name: Test Academy Exercises
+        runs-on: ubuntu-latest
+        steps:
+            -   name: Checkout Source code
+                uses: actions/checkout@v6
+
+            -   name: Setup Node.js
+                uses: actions/setup-node@v6
+                with:
+                    cache: npm
+                    cache-dependency-path: package-lock.json
+
+            -   name: Setup Python
+                uses: astral-sh/setup-uv@v7
+
+            -   name: Install Bats
+                run: |
+                    corepack enable
+                    npm install --only=dev
+
+            -   name: Test
+                run: npm run test:academy

.gitignore

@@ -28,3 +28,7 @@ codegen/*/generated/
 codegen/*/go.sum
 .github/styles/Microsoft
 .github/styles/write-good
+sources/academy/**/exercises/storage
+sources/academy/**/exercises/node_modules
+sources/academy/**/exercises/package*.json
+sources/academy/**/exercises/dataset.json

CONTRIBUTING.md

@@ -335,6 +335,12 @@ Add languages by adding new folders at the appropriate path level.
     - Run `vale sync` to download styles
     - Configure exceptions in `accepts.txt`
 
+### Testing
+
+- **Broken links**: [Periodic GitHub Action](.github/workflows/lychee.yml) checks broken links by [lychee](https://lychee.cli.rs/). If the Action fails, we manually fix the issues.
+
+- **Academy exercises**: At the end of each lesson in the academy courses, there are exercises that target real-world websites. Each exercise includes a solution, stored as a separate file containing executable code. These files are included in the docs using the `!!raw-loader` syntax. Each course has a [Bats](https://bats-core.readthedocs.io/) test file named `test.bats`. The tests run each solution as a standalone program and verify that it produces output matching the expected results. A [periodic GitHub Action](.github/workflows/test-academy.yml) runs all these tests using `npm run test:academy`. If the Action fails, we rework the exercises.
+
 ## Pull request process
 
 1. Follow [Conventional Commits](https://www.conventionalcommits.org/)

package-lock.json

@@ -40,6 +40,7 @@
         "lint:md:fix": "markdownlint '**/*.md' --fix",
         "lint:code": "eslint .",
         "lint:code:fix": "eslint . --fix",
+        "test:academy": "bats --print-output-on-failure -r .",
         "postinstall": "patch-package",
         "postbuild": "node ./scripts/joinLlmsFiles.mjs && node ./scripts/indentLlmsFile.mjs"
     },
@@ -48,6 +49,7 @@
         "@apify/tsconfig": "^0.1.0",
         "@types/react": "^19.0.0",
         "babel-plugin-styled-components": "^2.1.4",
+        "bats": "^1.13.0",
         "cross-env": "^10.0.0",
         "eslint": "^9.32.0",
         "eslint-plugin-react": "^7.37.5",

package.json

@@ -5,8 +5,10 @@ description: Lesson about building a Node.js application for watching prices. Us
 slug: /scraping-basics-javascript/downloading-html
 ---
 
+import CodeBlock from '@theme/CodeBlock';
 import LegacyJsCourseAdmonition from '@site/src/components/LegacyJsCourseAdmonition';
 import Exercises from '../scraping_basics/_exercises.mdx';
+import LegoExercise from '!!raw-loader!roa-loader!./exercises/lego.mjs';
 
 <LegacyJsCourseAdmonition />
 
@@ -184,28 +186,17 @@ Letting our program visibly crash on error is enough for our purposes. Now, let'
 
 <Exercises />
 
-### Scrape AliExpress
+### Scrape LEGO
 
-Download HTML of a product listing page, but this time from a real world e-commerce website. For example this page with AliExpress search results:
+Download HTML of a product listing page, but this time from a real world e-commerce website. For example this page with LEGO search results:
 
 ```text
-https://www.aliexpress.com/w/wholesale-darth-vader.html
+https://www.lego.com/en-us/themes/star-wars
 ```
 
 <details>
   <summary>Solution</summary>
-
-  ```js
-  const url = "https://www.aliexpress.com/w/wholesale-darth-vader.html";
-  const response = await fetch(url);
-
-  if (response.ok) {
-    console.log(await response.text());
-  } else {
-    throw new Error(`HTTP ${response.status}`);
-  }
-  ```
-
+  <CodeBlock language="js">{LegoExercise.code}</CodeBlock>
 </details>
 
 ### Save downloaded HTML as a file

sources/academy/webscraping/scraping_basics_javascript/04_downloading_html.md

@@ -5,8 +5,11 @@ description: Lesson about building a Node.js application for watching prices. Us
 slug: /scraping-basics-javascript/parsing-html
 ---
 
+import CodeBlock from '@theme/CodeBlock';
 import LegacyJsCourseAdmonition from '@site/src/components/LegacyJsCourseAdmonition';
 import Exercises from '../scraping_basics/_exercises.mdx';
+import F1AcademyTeamsExercise from '!!raw-loader!roa-loader!./exercises/f1academy_teams.mjs';
+import F1AcademyDriversExercise from '!!raw-loader!roa-loader!./exercises/f1academy_drivers.mjs';
 
 <LegacyJsCourseAdmonition />
 
@@ -183,22 +186,7 @@ https://www.f1academy.com/Racing-Series/Teams
 
 <details>
   <summary>Solution</summary>
-
-  ```js
-  import * as cheerio from 'cheerio';
-
-  const url = "https://www.f1academy.com/Racing-Series/Teams";
-  const response = await fetch(url);
-
-  if (response.ok) {
-    const html = await response.text();
-    const $ = cheerio.load(html);
-    console.log($(".teams-driver-item").length);
-  } else {
-    throw new Error(`HTTP ${response.status}`);
-  }
-  ```
-
+  <CodeBlock language="js">{F1AcademyTeamsExercise.code}</CodeBlock>
 </details>
 
 ### Scrape F1 Academy drivers
@@ -207,20 +195,5 @@ Use the same URL as in the previous exercise, but this time print a total count
 
 <details>
   <summary>Solution</summary>
-
-  ```js
-  import * as cheerio from 'cheerio';
-
-  const url = "https://www.f1academy.com/Racing-Series/Teams";
-  const response = await fetch(url);
-
-  if (response.ok) {
-    const html = await response.text();
-    const $ = cheerio.load(html);
-    console.log($(".driver").length);
-  } else {
-    throw new Error(`HTTP ${response.status}`);
-  }
-  ```
-
+  <CodeBlock language="js">{F1AcademyDriversExercise.code}</CodeBlock>
 </details>

sources/academy/webscraping/scraping_basics_javascript/05_parsing_html.md

@@ -5,8 +5,12 @@ description: Lesson about building a Node.js application for watching prices. Us
 slug: /scraping-basics-javascript/locating-elements
 ---
 
+import CodeBlock from '@theme/CodeBlock';
 import LegacyJsCourseAdmonition from '@site/src/components/LegacyJsCourseAdmonition';
 import Exercises from '../scraping_basics/_exercises.mdx';
+import WikipediaCountriesExercise from '!!raw-loader!roa-loader!./exercises/wikipedia_countries.mjs';
+import WikipediaCountriesSingleSelectorExercise from '!!raw-loader!roa-loader!./exercises/wikipedia_countries_single_selector.mjs';
+import GuardianF1TitlesExercise from '!!raw-loader!roa-loader!./exercises/guardian_f1_titles.mjs';
 
 <LegacyJsCourseAdmonition />
 
@@ -238,36 +242,7 @@ Djibouti
 
 <details>
   <summary>Solution</summary>
-
-  ```js
-  import * as cheerio from 'cheerio';
-
-  const url = "https://en.wikipedia.org/wiki/List_of_sovereign_states_and_dependent_territories_in_Africa";
-  const response = await fetch(url);
-
-  if (response.ok) {
-    const html = await response.text();
-    const $ = cheerio.load(html);
-
-    for (const tableElement of $(".wikitable").toArray()) {
-      const $table = $(tableElement);
-      const $rows = $table.find("tr");
-
-      for (const rowElement of $rows.toArray()) {
-        const $row = $(rowElement);
-        const $cells = $row.find("td");
-
-        if ($cells.length > 0) {
-          const $thirdColumn = $($cells[2]);
-          const $link = $thirdColumn.find("a").first();
-          console.log($link.text());
-        }
-      }
-    }
-  } else {
-    throw new Error(`HTTP ${response.status}`);
-  }
-  ```
+  <CodeBlock language="js">{WikipediaCountriesExercise.code}</CodeBlock>
 
   Because some rows contain [table headers](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th), we skip processing a row if `table_row.select("td")` doesn't find any [table data](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td) cells.
 
@@ -288,27 +263,7 @@ You may want to check out the following pages:
 
 <details>
   <summary>Solution</summary>
-
-  ```js
-  import * as cheerio from 'cheerio';
-
-  const url = "https://en.wikipedia.org/wiki/List_of_sovereign_states_and_dependent_territories_in_Africa";
-  const response = await fetch(url);
-
-  if (response.ok) {
-    const html = await response.text();
-    const $ = cheerio.load(html);
-
-    for (const element of $(".wikitable tr td:nth-child(3)").toArray()) {
-      const $nameCell = $(element);
-      const $link = $nameCell.find("a").first();
-      console.log($link.text());
-    }
-  } else {
-    throw new Error(`HTTP ${response.status}`);
-  }
-  ```
-
+  <CodeBlock language="js">{WikipediaCountriesSingleSelectorExercise.code}</CodeBlock>
 </details>
 
 ### Scrape F1 news
@@ -330,23 +285,5 @@ Max Verstappen wins Canadian Grand Prix: F1 – as it happened
 
 <details>
   <summary>Solution</summary>
-
-  ```js
-  import * as cheerio from 'cheerio';
-
-  const url = "https://www.theguardian.com/sport/formulaone";
-  const response = await fetch(url);
-
-  if (response.ok) {
-    const html = await response.text();
-    const $ = cheerio.load(html);
-
-    for (const element of $("#maincontent ul li h3").toArray()) {
-      console.log($(element).text());
-    }
-  } else {
-    throw new Error(`HTTP ${response.status}`);
-  }
-  ```
-
+  <CodeBlock language="js">{GuardianF1TitlesExercise.code}</CodeBlock>
 </details>