How to create interactive HTML/CSS labs? ​

We'll divide this part into 5 sections:

1. Creating lab metadata
2. Setting up lab defaults
3. Setting up lab challenges
4. Setting up evaluation script
5. Setting up test file

Introduction ​

This guide would assume that you already have created an interactive course from your instructor panel. If not, go here and set it up first

Step 1 - Creating lab metadata ​

• Add a new item lab in your course curriculum page

• A new lab item gets added. Click on the edit pencil button on the right. This should open the lab library widget in your instructor panel.

• You should now be able to write a quick lab name and press on "Create Lab" button. This would create a lab you would be able to edit.

• Once it is created, click on the "Edit" button and you'll arrive at lab designer view.

This is where you will add metadata to your labs and setup your labs for evaluation. Let's take a look at all the tabs here.

Lab Details ​

Lab details is the tab where you add two important things:

• Lab title
• Lab description

Once both of them are filled, it would appear as following:

Let's move to the next tab now.

Container Image ​

Container image should be set as "HTML/CSS" for HTML/CSS labs. The following software are available by default in this image:

• static-server npm package installed globally: static-server
• Puppeteer installation with Chrome for E2E testing (more on this in Evaluation tab)
• Node.js v14, Yarn, NPM, Bun.js

The following NPM packages (non-exhaustive list) are globally installed:

• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• @drizzle/[email protected]
• [email protected]

Lab Layout ​

Lab layout can be used to set a default layout in which the lab boots. We currently support the following layout types:

Terminal + IDE + Browser ​

This would include everything codedamn has to offer - a terminal at the bottom, an IDE in center (powered by Monaco on desktops, and CodeMirror on mobile phones), and a browser preview of (ideally) what user is working on. This is best if your playground runs a HTTP server.

Terminal + Browser ​

This layout is for times when you don't need IDE in place, and only want something hosted inside a browser - like a XSS challenge.

Terminal + IDE ​

This layout is for backend programming without website UI. This would only include a terminal and an IDE - like VS Code. For example - headless E2E testing, writing Python scripts, discord bots, etc.

Terminal only ​

This would not include anything, except for a terminal. Best for Linux/bash labs where you want users to exclusively work with terminals only.

Step 2 - Lab Defaults ​

Lab defaults section include how your lab environment boots. It is one of the most important parts because a wrong default environment might confuse your students. Therefore it is important to set it up properly.

When a codedamn playground boots, it can setup a filesystem for user by default. You can specify what the starting files could be, by specifying a git repository and a branch name:

Step 3 - Lab challenges ​

Next step is to setup challenges and evaluation for your lab. This is the part where your learners can learn the most because they will have to pass certain challenges.

This is the biggest advantage of using codedamn for hosting your course too - to make them truly interactive and hands-on for your users.

Let's start by setting up challenges.

The interface above can be used to add challenges to your lab. You can also add hints to every single challenge you put here.

Step 4 - Evaluation Script ​

Evaluation script is actually what runs when the user on the codedamn playground clicks on "Run Tests" button.

Since we have already written a pure evaluation script that runs and finally writes the JSON result to the UNIT_TEST_OUTPUT_FILE environment, all we have to do is trigger that script via Node.js.

The full path of the script is made available at run-time with another environment variable called TEST_FILE_NAME. Therefore, all we have to do is write the following in the evaluation script area:

#!/bin/bash
set -e 1

mkdir -p /home/damner/code/.labtests

cat > /home/damner/code/.labtests/package.json << EOF
{
    "type": "module"
}
EOF

cd /home/damner/code/.labtests
mv $TEST_FILE_NAME ./nodecheck.test.js

# import puppeteer doesn't work without it
npm link puppeteer

node nodecheck.test.js 2>&1 | tee evaluationscript.log

#!/bin/bash
set -e 1

mkdir -p /home/damner/code/.labtests

cat > /home/damner/code/.labtests/package.json << EOF
{
    "type": "module"
}
EOF

cd /home/damner/code/.labtests
mv $TEST_FILE_NAME ./nodecheck.test.js

# import puppeteer doesn't work without it
npm link puppeteer

node nodecheck.test.js 2>&1 | tee evaluationscript.log

This will make sure we run the full Node.js script and write the results properly for the playground IDE to read. It would look like the following:

Note: You can setup a full testing environment in this block of evaluation script (installing more packages, etc. if you want). However, your test file will be timed out after 30 seconds. Therefore, make sure, all of your testing can happen within 30 seconds.

Step 5 - Test file ​

You will see a button named Edit Test File in the Evaluation tab. Click on it.

When you click on it, a new window will open. This is a test file area.

You can write anything here. Whatever script you write here, can be executed from the Test command to run section inside the evaluation tab we were in earlier.

The point of having a file like this to provide you with a place where you can write your evaluation script.

For HTML/CSS labs, you can use the default test file of Node.js (Puppeteer) evaluation:

The moment you select the Node.js (Puppeteer), the following code should appear in your editor:

// !! Boilerplate code starts
import fs from 'node:fs'
import puppeteer from 'puppeteer'

// testlog is a log of test results
const testlog = []

// launch the headless browser for testing
const browser = await puppeteer.launch({
	executablePath: '/usr/bin/google-chrome',
	headless: true,
	args: [
		'--no-sandbox',
		'--disable-setuid-sandbox',
		'--disable-dev-shm-usage',
		'--disable-accelerated-2d-canvas',
		'--no-first-run',
		'--no-zygote',
		'--single-process',
		'--disable-gpu',
	],
})
const page = await browser.newPage()

// wait for server to come online
await page.goto('http://localhost:1337')

// add jQuery and chai for unit testing support if you want
await Promise.all([
	page.addScriptTag({
		url: 'https://code.jquery.com/jquery-3.5.1.slim.min.js',
	}),
	page.addScriptTag({
		url: 'https://cdnjs.cloudflare.com/ajax/libs/chai/4.2.0/chai.min.js',
	}),
])

// add chai-dom
await page.addScriptTag({
	url: 'https://cdn.jsdelivr.net/npm/[email protected]/chai-dom.min.js',
})

// !! Boilerplate code ends

// Start your tests here in individual try-catch block

{
	const result = await page.evaluate(async () => {
		const { expect } = window.chai
		try {
			expect(
				document.body.innerHTML.toLowerCase().includes('hello world')
			).to.be.true
			return { status: 'pass' }
		} catch (error) {
			return {
				status: 'error',
				error: error.message || 'Challenge failed',
			}
		}
	})

	testlog.push(result)
}

{
	const result = await page.evaluate(async () => {
		const { expect } = window.chai
		try {
			expect(
				document.body.innerHTML
					.toLowerCase()
					.includes('hello world again')
			).to.be.true
			return { status: 'pass' }
		} catch (error) {
			return {
				status: 'error',
				error: error.message || 'Challenge failed',
			}
		}
	})

	testlog.push(result)
}

// very important for the final length of \`testlog\` array to match the number of challenges, in this case - 2.

// write the test log
fs.writeFileSync(
	'/home/damner/code/.labtests/testlog.json',
	JSON.stringify(testlog)
)

// write the results array boolean. this will map to passed or failed challenges depending on the boolean value at the challenge index
fs.writeFileSync(
	process.env.UNIT_TEST_OUTPUT_FILE,
	JSON.stringify(testlog.map((result) => result.status === 'pass'))
)

await browser.close().catch((err) => {})

// Exit the process
process.exit(0)

// !! Boilerplate code starts
import fs from 'node:fs'
import puppeteer from 'puppeteer'

// testlog is a log of test results
const testlog = []

// launch the headless browser for testing
const browser = await puppeteer.launch({
	executablePath: '/usr/bin/google-chrome',
	headless: true,
	args: [
		'--no-sandbox',
		'--disable-setuid-sandbox',
		'--disable-dev-shm-usage',
		'--disable-accelerated-2d-canvas',
		'--no-first-run',
		'--no-zygote',
		'--single-process',
		'--disable-gpu',
	],
})
const page = await browser.newPage()

// wait for server to come online
await page.goto('http://localhost:1337')

// add jQuery and chai for unit testing support if you want
await Promise.all([
	page.addScriptTag({
		url: 'https://code.jquery.com/jquery-3.5.1.slim.min.js',
	}),
	page.addScriptTag({
		url: 'https://cdnjs.cloudflare.com/ajax/libs/chai/4.2.0/chai.min.js',
	}),
])

// add chai-dom
await page.addScriptTag({
	url: 'https://cdn.jsdelivr.net/npm/[email protected]/chai-dom.min.js',
})

// !! Boilerplate code ends

// Start your tests here in individual try-catch block

{
	const result = await page.evaluate(async () => {
		const { expect } = window.chai
		try {
			expect(
				document.body.innerHTML.toLowerCase().includes('hello world')
			).to.be.true
			return { status: 'pass' }
		} catch (error) {
			return {
				status: 'error',
				error: error.message || 'Challenge failed',
			}
		}
	})

	testlog.push(result)
}

{
	const result = await page.evaluate(async () => {
		const { expect } = window.chai
		try {
			expect(
				document.body.innerHTML
					.toLowerCase()
					.includes('hello world again')
			).to.be.true
			return { status: 'pass' }
		} catch (error) {
			return {
				status: 'error',
				error: error.message || 'Challenge failed',
			}
		}
	})

	testlog.push(result)
}

// very important for the final length of \`testlog\` array to match the number of challenges, in this case - 2.

// write the test log
fs.writeFileSync(
	'/home/damner/code/.labtests/testlog.json',
	JSON.stringify(testlog)
)

// write the results array boolean. this will map to passed or failed challenges depending on the boolean value at the challenge index
fs.writeFileSync(
	process.env.UNIT_TEST_OUTPUT_FILE,
	JSON.stringify(testlog.map((result) => result.status === 'pass'))
)

await browser.close().catch((err) => {})

// Exit the process
process.exit(0)

Let us understand what is happening here exactly:

• Remember that we can code anything in this file and then execute it later. In this example, we're writing a Node.js script from scratch.
• Remember that we already have puppeteer with headless chrome pre-installed in codedamn playgrounds for HTML/CSS. Therefore, we can import it directly.
• In the first part of run function, we start a headless puppeteer browser.
• We then visit http://localhost:1337. At this point, I would highly recommend you to read How port mapping works for codedamn playgrounds, if you haven't yet.
• From this point onwards, we have some try-catch blocks. But why? Because we want to populate an array results and then finally write this array to a file inside environment variable UNIT_TEST_OUTPUT_FILE
• Let's say, [true, false] is written to the file process.env.UNIT_TEST_OUTPUT_FILE. In that case, the first challenge would be marked as passed in the IDE, and the second challenge would be marked as failed:

• Whatever your mapping of final JSON boolean array written in process.env.UNIT_TEST_OUTPUT_FILE is, it is matched exactly to the results on the playground. For example, if the array written is [true, false, true, true], the following would be the output on playground:

• Note: If your results array contain less values than challenges added back in the UI, the "extra" UI challenges would automatically stay as "false". If you add more challenges in test file, the results would be ignored. Therefore, it is important that the results.length is same as the number of challenges you added in the challenges UI.

• We then also add jQuery and chai for assisting with testing. Although it is not required as long as you can populate the results array properly.

This completes your evaluation script for the lab. Your lab is now almost ready for users.

Setup Verified Solution (Recommended) ​

Verified solution is highly recommended. To setup a verified solution for your lab, once your lab is ready, all you have to do is click on "Test lab", write code that passes your lab, and run that code once.

Once you do that, your lab would be marked a lab having verified solution. It also helps students as we can show them a Monaco diff editor showing the verified solution from the creator (you).

At this point, your lab is complete. You can now link this lab in your course, ready to be served to thousands of students 😃 Watch the video tutorial below to understand: