codingame_tools.client.common.protocol.test_session¶
JSON-serializable dataclasses for the TestSession service's startTestSession and play Codingame API methods.
This is the API called by the web client when a codingamer clicks "Solve in IDE" on a puzzle (startTestSession), and when they click "Test"/"Run" to run their code against a single test case (play, as opposed to a full "Submit"). Only a single example (a previously-solved community puzzle) has been observed so far, so field optionality beyond what's noted below is unconfirmed.
module-attribute
¶
CgHtml = str
Rendered HTML for display of the problem statement, input/output descriptions, and constraints. This is derived from the CgMarkdown content. It is rendered by the server and returned in the API response.
module-attribute
¶
CgStubGenerator = str
A script in CodingGame's stub generation language that can generate a stub solution for the puzzle in any supported programming language. See https://www.codingame.com/playgrounds/40701/help-center/stub-generator
module-attribute
¶
CgSolutionLanguage = str
The programming language used for the reference solution, e.g. "Python3", "Java", "C++", etc.
Code submitted/played (TestSession/play, TestSession/submit, contribution
updateContribution/createContribution) runs server-side in a sandbox with a specific
version and, for some languages, specific bundled libraries--relevant to know when writing a
solution that assumes a particular language feature or library is available. Confirmed:
- Python3: 3.11.5, with NumPy, pandas, and SciPy available.
Other languages' exact versions/bundled libraries aren't catalogued here yet--see https://www.codingame.com/playgrounds/40701/help-center/languages-versions (a client-rendered page; fetching it programmatically only returns the loading shell, not the real content, so this couldn't be filled in automatically--add entries here as they're confirmed for other languages actually in use).
File-extension mapping for a CgSolutionLanguage lives in codingame_tools.language
(get_language(cg_id).extension / get_language_by_extension(ext)), not here--this module is
wire-protocol schema only.
dataclass
¶
CgLastActivityContributor(user_id, public_handle, extra_data=dict(), pseudo=None, avatar=None, cover=None)
Bases: JSONWizardX
The codingamer who authored a puzzle, as embedded in CgLastActivityPuzzle.contributor.
class-attribute
instance-attribute
¶
pseudo = None
The contributor's display name. Not always present--confirmed live (2026-07-31, via cg
puzzle import resolving a title search to a puzzle with such a contributor): a
never-configured/minimal account can omit pseudo entirely, same already-documented
pattern as CgCodingamer.pseudo/CgCodingamerFollower.pseudo.
class-attribute
instance-attribute
¶
avatar = None
The binary image ID of the contributor's avatar image.
class-attribute
instance-attribute
¶
cover = None
The binary image ID of the contributor's cover image.
dataclass
¶
CgTestSessionAnswer(extra_data=dict(), code=None, programming_language_id=None)
Bases: JSONWizardX
The codingamer's current saved answer for a test session, as embedded in
CgTestSessionQuestion.answer.
code/programming_language_id are both Optional--confirmed live (2026-07-31): answer
itself can be present as an empty JSON object ({}), NOT null/absent, even though no
solution was ever submitted--i.e. CgTestSessionQuestion.answer being non-None does NOT
by itself mean a real answer exists; check code/programming_language_id here too. The
exact trigger for empty-object vs. null/absent isn't confirmed--the one observed case
had a test session already created (the puzzle had been opened/viewed in the IDE) but no
solution ever submitted, which suggests "a session exists for this puzzle" (not literally
"ever attempted") may be what actually determines it; not fully verified either way.
class-attribute
instance-attribute
¶
code = None
The codingamer's saved source code. None for the empty placeholder object--see class
docstring.
class-attribute
instance-attribute
¶
programming_language_id = None
The programming language code is written in. Same None-for-empty-placeholder caveat as
code.
dataclass
¶
CgAvailableLanguage(id, name, extra_data=dict())
dataclass
¶
CgTestSessionContribution(id, public_handle, status, moderators, contribution_type=Alias('type'), extra_data=dict())
Bases: JSONWizardX
Lightweight contribution metadata, as embedded in
CgTestSessionQuestionDetails.contribution. A much smaller summary than
CgContribution (contribution.py).
class-attribute
instance-attribute
¶
contribution_type = Alias('type')
The type of the contribution, e.g. "PUZZLE_INOUT".
dataclass
¶
CgTestSessionTestCase(index, input_binary_id, output_binary_id, label, extra_data=dict())
Bases: JSONWizardX
A single test case, as embedded in CgTestSessionQuestionDetails.test_cases. Unlike
CgTestCase (contribution.py), only references binary IDs for the input/output
content rather than including it inline.
NOTE: checked for schema overlap with CgTestCase (2026-07-26)--the two share zero field
names (this one: index/input_binary_id/output_binary_id/label; CgTestCase:
title/test_in/test_out/is_test/is_validator/need_validation). They represent the same
underlying puzzle test case from two different API contexts (solve/IDE vs.
contribution-authoring), so a shared conceptual model (e.g. one canonical "puzzle test
case" type that each endpoint's shape adapts into/out of) may be worth revisiting if a
third endpoint's test-case shape turns up, but there wasn't enough justification to force
a merge from just these two structurally-disjoint shapes alone.
instance-attribute
¶
output_binary_id
Binary ID of the test case's expected output content.
dataclass
¶
CgTestSessionQuestionDetails(id, title, statement, stub_generator, duration, index, initial_id, user_id, available_languages, test_cases, question_type=Alias('type'), extra_data=dict(), contributor=None, contribution=None)
Bases: JSONWizardX
Full puzzle/question details, as embedded in CgTestSessionQuestion.question.
instance-attribute
¶
id
Numeric ID of the question (matches the enclosing puzzle's question ID, not necessarily
CgTestSessionPuzzle.id).
instance-attribute
¶
stub_generator
Stub-generation script for this puzzle; see CgStubGenerator.
instance-attribute
¶
duration
Unclear precise semantics (not documented)--observed as a very large number of milliseconds; possibly a maximum/elapsed session duration.
instance-attribute
¶
index
Unclear precise semantics; observed as 0 in the only example so far.
instance-attribute
¶
initial_id
Unclear precise semantics; observed equal to id in the only example so far.
instance-attribute
¶
user_id
Unclear precise semantics; observed equal to contributor.user_id in the only example
so far--possibly redundant with it.
instance-attribute
¶
available_languages
Programming languages available to solve this puzzle in.
instance-attribute
¶
test_cases
The puzzle's test cases (metadata only--content is referenced by binary ID).
class-attribute
instance-attribute
¶
question_type = Alias('type')
Discriminator for the kind of question, e.g. "MULTIPLE_LANGUAGES". Only one value observed so far.
class-attribute
instance-attribute
¶
contributor = None
The codingamer who authored this puzzle, or None for a puzzle CodinGame itself provides.
Confirmed live (2026-08-02) absent entirely--not null--for an official puzzle
("Temperatures"), which also reports the sentinel user_id: -2. Only community
contributions have an author to name.
class-attribute
instance-attribute
¶
contribution = None
Lightweight contribution metadata, or None for a puzzle CodinGame itself provides--an
official puzzle was never a community contribution, so there's nothing to describe.
Confirmed live (2026-08-02) absent entirely for "Temperatures". Note this is the only source
of a puzzle's contribution_type, so that is simply unknowable for an official puzzle--see
codingame_tools.puzzle_manager.manager.CgPuzzleManager.import_, which treats absence as a
standard in/out puzzle rather than refusing every official puzzle outright.
dataclass
¶
CgTestSessionQuestion(question, extra_data=dict(), last_submission_id=None, answer=None)
Bases: JSONWizardX
The active question in a test session, as returned in CgTestSession.current_question.
class-attribute
instance-attribute
¶
last_submission_id = None
Numeric ID of the codingamer's last submission for this question. Confirmed live
(2026-07-31) to be absent entirely (not just null) when no solution has ever been
submitted--same underlying "session exists, never submitted" case as answer's
empty-object caveat; see CgTestSessionAnswer's docstring.
class-attribute
instance-attribute
¶
answer = None
The codingamer's current saved answer. Populated (with the codingamer's own previously
submitted code) once a solution has been submitted. Confirmed live (2026-07-31), this
field can also be present-but-empty (a CgTestSessionAnswer with code/
programming_language_id both None) rather than None/absent, when no solution was
ever submitted--check those two fields, not just answer is None, to tell "has a real
saved answer" from "no answer yet." See CgTestSessionAnswer's docstring for what is/
isn't confirmed about exactly when each shape (null vs. empty object) occurs.
dataclass
¶
CgTestSessionPuzzle(id, handle, pretty_id, title, level, details_page_url, forum_post_id, extra_data=dict(), hints=None)
Bases: JSONWizardX
Lightweight puzzle metadata, as embedded in CgTestSession.puzzle. A much smaller
summary than CgLastActivityPuzzle (last_activities.py).
instance-attribute
¶
handle
Opaque handle for the puzzle (distinct from CgTestSession.test_session_handle).
instance-attribute
¶
pretty_id
URL-friendly slug for the puzzle, e.g. "literary-alfabet-soupe".
instance-attribute
¶
details_page_url
Relative URL path to the puzzle's details/training page.
instance-attribute
¶
forum_post_id
Relative URL path (minus domain) to the puzzle's discussion forum thread.
class-attribute
instance-attribute
¶
hints = None
Hints available for this puzzle. Only observed as an empty list so far, so element shape is unknown.
dataclass
¶
CgTestSessionQuestionSummary(question_id, title, has_result, extra_data=dict(), score=None)
Bases: JSONWizardX
A single entry in CgTestSession.questions--a summary of one question in the test
session (as opposed to CgTestSession.current_question's full details).
instance-attribute
¶
question_id
Numeric ID of the question; matches CgTestSessionQuestionDetails.id for the current
question.
instance-attribute
¶
has_result
Whether the codingamer has a recorded result (e.g. a submission) for this question.
class-attribute
instance-attribute
¶
score = None
The codingamer's score for this question, from 0.0 to 1.0. Confirmed live (2026-07-31) to
be absent entirely when has_result is False--nothing to score yet.
dataclass
¶
CgTestSession(test_session_handle, test_session_id, user_id, test_type, direct, need_account, shareable, show_replay_prompt, current_question, puzzle, questions, extra_data=dict())
Bases: JSONWizardX
The complete response to TestSession/startTestSession--the interactive IDE session state created when a codingamer clicks "Solve in IDE" on a puzzle.
instance-attribute
¶
test_session_handle
Opaque handle identifying this test session (matches the handle argument passed in).
instance-attribute
¶
direct
Unclear precise semantics; observed False in the only example so far.
instance-attribute
¶
need_account
Whether an account is required to use this test session (e.g. False for a fully public trial session).
instance-attribute
¶
shareable
Whether the test session can be shared (e.g. via a public results link).
instance-attribute
¶
show_replay_prompt
Whether the UI should prompt the codingamer to replay/retry.
instance-attribute
¶
questions
Summary of all questions in this test session (usually just the one in
current_question).
dataclass
¶
CgMultipleLanguagesTestParams(test_index, extra_data=dict())
Bases: JSONWizardX
Test-case selection parameters specific to puzzles whose
CgTestSessionQuestionDetails.question_type == "MULTIPLE_LANGUAGES", as embedded in
CgPlayRequest.multiple_languages. Other question types likely need a different,
not-yet-modeled params object instead.
instance-attribute
¶
test_index
1-based index selecting which of the puzzle's test cases to run against; see
CgTestSessionTestCase.index.
dataclass
¶
CgPlayRequest(code, programming_language_id, extra_data=dict(), multiple_languages=None)
Bases: JSONWizardX
The request payload for TestSession/play: run a codingamer's code against a single test case within a test session.
instance-attribute
¶
programming_language_id
The programming language code is written in.
class-attribute
instance-attribute
¶
multiple_languages = None
Test-case selection, for question_type == "MULTIPLE_LANGUAGES" puzzles; see
CgMultipleLanguagesTestParams. Presumably required in that case and unset/differently-
shaped otherwise, but this is unconfirmed--only one question type has been observed.
dataclass
¶
CgSubmitRequest(code, programming_language_id, extra_data=dict())
Bases: JSONWizardX
The request payload for TestSession/submit: submit a final solution to a puzzle for
credit, validated against the puzzle's private validator test cases (as opposed to
TestSession/play, which only runs one local test case). Unlike CgPlayRequest, no
multiple_languages-style test-case selector is used here--submission validates against
every validator test case, not one chosen local test.
dataclass
¶
CgPlayStackFrame(container, function, line, location, extra_data=dict())
Bases: JSONWizardX
A single stack frame in CgPlayError.stacktrace.
instance-attribute
¶
function
Name of the function/scope the frame is in. Observed as descriptive text rather than a
bare identifier for top-level frames, e.g. " in
instance-attribute
¶
location
Unclear precise semantics; observed as "ANSWER" (i.e. the codingamer's own code) in every frame so far--presumably distinguishes the codingamer's code from puzzle-provided harness/boilerplate code in a full stack trace.
dataclass
¶
CgPlayError(message, stacktrace, extra_data=dict())
Bases: JSONWizardX
A runtime/compile-time error from running the code, as returned in
CgPlayResult.error--present instead of a normal CgPlayResult.comparison result when
the code failed to compile/parse or raised an uncaught exception.
dataclass
¶
CgPlayComparison(success, extra_data=dict(), expected=None, found=None)
Bases: JSONWizardX
The result of comparing the code's output against the test case's expected output, as
returned in CgPlayResult.comparison.
class-attribute
instance-attribute
¶
expected = None
The test case's expected output. Not always present--absent when the code raised an
error before producing any comparable output (see CgPlayResult.error).
class-attribute
instance-attribute
¶
found = None
The code's actual output (possibly truncated, e.g. observed ending in "..."). Not always present--absent both on success and when the code errored out; only observed populated for a genuine wrong-answer mismatch.
dataclass
¶
CgPlayResult(output, comparison, extra_data=dict(), error=None)
Bases: JSONWizardX
The complete response to TestSession/play.
instance-attribute
¶
output
Combined stdout+stderr produced by running the code, interleaved into a single stream
exactly as shown in the IDE's console output pane--confirmed empirically (code that
wrote to stderr in a loop, then a single stdout line, produced an output containing
all the stderr lines followed by the stdout line). Empty if the code errored out before
producing any output.
comparison, by contrast, is computed from genuine stdout only--also confirmed
empirically (the same test's comparison.expected correctly reflected comparing just
the one real stdout line against the puzzle's expected output, unaffected by the
interleaved stderr noise in output).
instance-attribute
¶
comparison
Comparison of the code's actual stdout (not output, which also includes stderr)
against the test case's expected output.
class-attribute
instance-attribute
¶
error = None
Present if the code failed to compile/parse or raised an uncaught exception. comparison
is still present alongside it in that case (with success: False, and expected set but
found absent).